Skip to content

Changelog

All notable changes to frappe-stack are documented here.

The format follows Keep a Changelog. This project adheres to Semantic Versioning.

[Unreleased]

Removed (D-10 plugin-only refactor — 2026-05-05)

  • apps/stack_core/ — the entire Frappe support app (~30 files) is gone. The plugin now uses Frappe's stock REST API (POST /api/resource/DocType, POST /api/resource/Workflow, etc.) with token authentication. Nothing custom-installed on the Frappe site.
  • docs/operators/installing-stack-core.md — no longer relevant; the plugin install is two slash commands, not a bench install-app.
  • Stack Audit Log and Stack Blueprint and Stack Workflow Def DocTypes — replaced by Frappe's built-in Activity Log + the local .frappe-stack/audit.jsonl. Experiment Assignment is now a regular DocType created on demand by /frappe-stack:experiment define via stock REST.

Changed

  • All agents, slash commands, skills, catalog pages, hook scripts, and Builder Protocol files reframed to call stock Frappe REST instead of stack_core.api.*. Validators and audit logging happen client-side in the plugin; Frappe's permission system and Activity Log handle the server side.
  • D-10 added and confirmed: plugin-only architecture; the original Phase 2/7 deliverables (the stack_core Frappe app and its git_bridge module) are superseded.

Added (Phase 0 — 2026-05-01)

  • Initial Builder Protocol docs: README.md, PRD.md, PLAN.md, SECURITY.md, CLAUDE.md, HEARTBEAT.md.
  • Decision register opened with D-01..D-09 (D-09 confirmed: infra/ deferred to post-v0.1).

Added (Phase 1 — 2026-05-03)

  • .claude-plugin/plugin.json — manifest, name=frappe-stack, version=0.1.0.
  • .claude-plugin/marketplace.json — single-plugin self-marketplace.
  • .claude-plugin/README.md — install + namespace docs.
  • LICENSE (MIT).
  • D-02..D-08 confirmed.

Added (Phase 2 + 7 — 2026-05-03)

  • apps/stack_core/ Frappe support app with:
  • DocTypes: Stack Blueprint, Stack Workflow Def, Experiment Assignment, Stack Audit Log (+ tests).
  • API: doctype_builder, workflow_builder, config_builder, fixtures.export, diff.diff. All whitelisted, permission-checked, audit-logged via @audited decorator.
  • Guardrails: schema_validator (Draft 2020-12 JSON-Schema per blueprint type), fieldtype_whitelist (Code/Password/Attach gated), reserved_names (refuses Frappe core + 'Stack ' prefix), workflow_validator (terminal-state, role-on-state, traffic-split-sums-to-100), permission_enforcer (refuses prod direct writes, blocks audit-tagged hard-delete).
  • Git bridge (Phase 7): exporter (per-blueprint JSON), committer (GitPython), pr_opener (gh CLI + REST fallback), differ (3-bucket structured diff), applier (idempotent git→site), daily reconcile_drift scheduled task.
  • 5 test modules covering DocType controllers, guardrails, git bridge, API endpoints. Coverage target: ≥ 80%.

Added (Phase 3 — 2026-05-03)

  • 16 skills:
  • platform/: frappe-platform (4-layer model, config-vs-code decision tree), frappe-permissions, frappe-patterns, frappe-api.
  • building/: designing-forms, modeling-workflows, building-dashboards, composing-reports, wiring-integrations, designing-experiments.
  • process/: git-roundtrip, promoting-changes, writing-specs, running-qa, managing-tickets.
  • builder-protocol/ (the meta-skill — when to use the four protocol files).

Added (Phases 4–6 — 2026-05-03)

  • 8 agents: engineer, reviewer, tester, deployer, analyst, migrator, documenter, orchestrator.
  • 9 slash commands: /frappe-stack:init, :build, :pull, :push, :diff, :promote, :experiment, :review, :ship.
  • 6 safety hooks declared in hooks/hooks.json:
  • block_dangerous_bash — rm -rf /, bench drop-site, git push --force to protected branches, DROP, DELETE without WHERE.
  • block_direct_prod_api — refuses mutating call to host flagged is_production=1.
  • block_ignore_permissions — ignore_permissions=True, allow_guest=True, hardcoded role checks.
  • block_credential_leak — AKIA*, GitHub tokens, private keys, hardcoded api_key=/Bearer literals.
  • block_fstring_sql — f-string / .format() / % SQL in *.py.
  • audit_local (PostToolUse) — append .frappe-stack/audit.jsonl row per Bash/Edit/Write.
  • heartbeat_check (Stop) — prompts if PLAN.md changed but HEARTBEAT.md didn't.

Added (Phase 8 — 2026-05-03)

  • A/B in workflows is integrated across phases ⅔/5:
  • Stack Workflow Def.experiment_id + experiment_status fields.
  • Experiment Assignment DocType (deterministic by hash(experiment_id || doc.name)).
  • Split-state validator in workflow_validator.py.
  • building/designing-experiments skill.
  • /frappe-stack:experiment command (define / status / pause / resume / promote / abandon).

Added (Phase 9 — 2026-05-03)

  • docs/walkthroughs/ — 4 PM-facing walkthroughs (first DocType, first workflow, first experiment, first promotion).
  • docs/operators/ — 2 DevOps runbooks (installing stack_core, rotating keys).

Added (Prompt coaching — 2026-05-03)

  • coach_user_prompt.py — UserPromptSubmit hook. Scans every free-text prompt at typing time, before Claude sees it.
  • Blocks on: real PII (Aadhaar / PAN / Indian mobile), DROP TABLE / TRUNCATE, force-merge / bypass-review intent, force-push to protected branches.
  • Coaches (injects hidden context) on: vague build intents (suggests the matching slash command), production-write intents, permission bypass, elevated fieldtype mentions, schema-rename intents, A/B intents without a question, multi-blueprint features without a spec, integration setups.
  • skills/process/prompt-coaching/SKILL.md — reference for what the hook does and how to tune false positives.

Added (GitHub Pages site — 2026-05-05)

  • mkdocs.yml — MkDocs Material config (light/dark palette, search, nav tabs, code copy, edit-on-GitHub buttons).
  • requirements-docs.txt — pinned mkdocs, mkdocs-material, pymdown-extensions, pygments.
  • .github/workflows/docs.yml — auto-deploys on push to main when docs / Builder-Protocol / mkdocs files change. Stages root-level Builder Protocol files (PRD.md, PLAN.md, SECURITY.md, CLAUDE.md, HEARTBEAT.md, CHANGELOG.md, CONTRIBUTING.md) into docs/ at build time so they appear under the Project tab without breaking the repo's directory layout. Uses actions/deploy-pages@v4 (no gh-pages branch needed).
  • Renamed docs/README.md → docs/index.md (MkDocs landing-page convention). Top-level repo browsers still land on the root README.md.
  • Site lives at https://dhwani-ris.github.io/frappe-stack/ once Pages is enabled in GitHub repo settings (Source: GitHub Actions).

Crosses the D-09 deferral line slightly (D-09 deferred infra/ Docker / CI / pre-commit). Pages is treated as docs publishing, not code CI/CD — separate concern, fine to land now.

Added (Public-readiness pass — 2026-05-05)

  • CONTRIBUTING.md — onboarding for skills / agents / commands / hooks / stack_core features / bug fixes / docs. Conventional commits, security disclosure path, PR review criteria.
  • .github/ISSUE_TEMPLATE/bug_report.md — structured bug template with severity ladder.
  • .github/ISSUE_TEMPLATE/feature_request.md — 5-section template that mirrors writing-specs skill (problem / user / solution-shape / out-of-scope / metric).
  • .github/ISSUE_TEMPLATE/skill_proposal.md — for proposing new skills with trigger phrases, refusals, and pairings.
  • .github/PULL_REQUEST_TEMPLATE.md — surfaces reviewer / tester output + the security checklist (no ignore_permissions=True, no allow_guest=True, no f-string SQL, etc.).

Removed (2026-05-05)

  • References to the private prody-dris/mgrant-stack repo in README.md and PRD.md. Outsiders saw 404s. Replaced with a generic "internal reference" note where appropriate.

Added (Documentation hub — 2026-05-05)

  • docs/README.md — top-level documentation index with how-the-pieces-fit diagram.
  • docs/skills.md — full catalog of all 17 skills with trigger phrases, purpose, and refusals.
  • docs/agents.md — all 8 agents with model choice, tools, pairings, refusals.
  • docs/commands.md — all 9 slash commands with arguments, refusals, typical-flow diagram.
  • docs/hooks.md — all 8 hooks across 4 lifecycle events with the layered-enforcement matrix.
  • docs/architecture.md — three-actor diagram, B+ hybrid sync model, end-to-end build flow, end-to-end promote flow, DocType layout, layered enforcement, failure modes.
  • README.md — refreshed top-level: install instructions, quick-links table, "what's in the box" inventory.

Deferred to post-v0.1 (D-09)

  • infra/: Docker compose, CI workflows, pre-commit hooks. Will port from dhwani-ris/frappe_dhwani_base when reopened.
  • Smoke-test of plugin install in a clean Claude Code session (cannot be done from inside a session).
  • Live bench test execution to confirm coverage meets the 80% target.