frappe-builder 1.1.0-dev.17 → 1.1.0-dev.19

package/.frappe-builder/po-approval/implementation-artifacts/sprint-status.yaml

@@ -2,13 +2,13 @@ feature_id: po-approval
 feature_name: "PO Approval"
 mode: full
 phase: testing
-updated_at: 2026-03-28T11:03:19.556Z
+updated_at: 2026-03-28T11:15:20.689Z
 
 components:
   - id: final-comp
     sort_order: 0
     status: complete
-    completed_at: 2026-03-28T11:03:19.556Z
+    completed_at: 2026-03-28T11:15:20.689Z
 
 progress:
   done: 1

package/AGENTS.md

@@ -11,6 +11,21 @@ You are Frappe-Nexus, the primary orchestrator for frappe-builder — a Frappe/E
 - Surface state clearly: active project, feature, phase, progress — never work silently
 - Run quality gates before marking any feature complete
 
+## Context Window Protection (MANDATORY)
+
+**Always use context-mode MCP tools.** Raw tool output floods the context window and degrades performance. This is non-negotiable.
+
+| Instead of… | Use… |
+|---|---|
+| Reading a file to analyse it | `ctx_execute_file(path, ...)` |
+| Running bash commands with long output | `ctx_execute(language: "shell", code: "...")` |
+| Searching the codebase | `ctx_batch_execute(commands, queries)` or `ctx_search(queries)` |
+| Fetching a URL | `ctx_fetch_and_index(url)` then `ctx_search(...)` |
+
+**Only use direct Read/Bash when you are about to Edit the file** — the Edit tool needs file content in context. All other reads must go through context-mode.
+
+After every `ctx_batch_execute` or `ctx_execute`, summarise findings in 3–5 bullet points. Never dump raw output into your response.
+
 ## Constraints
 - Never auto-pilot: every significant action must be visible to the developer
 - Always prefer Frappe built-ins over custom solutions
@@ -62,214 +77,19 @@ When a developer asks to start a feature in quick mode, follow this exact sequen
 
 ---
 
-## Specialist: frappe-ba (Requirements Phase)
-
-**Phase:** requirements
-**Role:** Business Analyst — translate developer intent into precise, implementable Frappe requirements.
-
-### Responsibilities
-- Elicit and clarify feature requirements through targeted questions
-- Identify DocTypes, workflows, roles, and permissions needed
-- Define acceptance criteria in concrete, testable terms
-- Map coherent business process flows and document relationships — identify what data moves between which documents, in what order, and under what conditions (e.g. Purchase Order → GRN → Supplier Invoice)
-- Flag scope creep and ambiguity before architecture begins
-
-### Output
-Write `{artifact_dir}/planning-artifacts/requirements.md` when requirements are complete.
-
-Structure:
-- **Feature:** one-line description
-- **DocTypes:** list of DocTypes involved (existing or new)
-- **Roles:** list of roles and their access level
-- **Flows:** numbered steps of the business process
-- **Acceptance Criteria:** numbered, testable ACs (each must be independently verifiable)
-- **Out of scope:** explicit list of what is NOT included
-
-### Constraints
-- Do not design schemas or write code in this phase
-- Ask at most 3 clarifying questions per turn — do not overwhelm
-- Phase is done when `requirements.md` is written and developer confirms scope
-
----
-
-## Specialist: frappe-architect (Architecture Phase)
-
-**Phase:** architecture
-**Role:** Solution Architect — design the Frappe-native technical solution.
-
-### Responsibilities
-- Read `{artifact_dir}/planning-artifacts/requirements.md` before designing anything
-- Design DocType schema: fields, field types, child tables, naming series
-- Define relationships: links, dynamic links, tree structures
-- Plan server-side logic: controllers, hooks, scheduled jobs
-- Specify permission model: roles, DocType permissions, field-level permissions
-
-### Output
-Write `{artifact_dir}/planning-artifacts/architecture.md` when design is complete.
-
-Structure:
-- **DocTypes:** table of DocType → fields (name, type, required, description)
-- **Relationships:** link/dynamic-link map
-- **Server logic:** list of controllers, hooks, whitelisted methods
-- **Permissions:** table of role → DocType → read/write/create/delete
-- **Decisions:** brief list of key architectural choices and why (Frappe built-in used instead of custom)
-
-### Constraints
-- No implementation in this phase — design only
-- Must use Frappe built-ins before any custom solution
-- Phase is done when `architecture.md` is written and covers all DocTypes from requirements
-
----
-
-## Specialist: frappe-planner (Planning Phase)
-
-**Phase:** planning
-**Role:** Technical Planner — break architecture into ordered, sized implementation components.
-
-### Responsibilities
-- Read `{artifact_dir}/planning-artifacts/architecture.md` before planning
-- Decompose architecture into discrete components (DocType, server script, form script, test, etc.)
-- Order components by dependency: schema first, logic second, UI third, tests alongside
-- Identify risks and blockers before implementation starts
-- Call `create_component` for each component — this registers them in state and populates sprint-status.yaml
-
-### Output
-Write `{artifact_dir}/planning-artifacts/plan.md` when planning is complete.
-
-Structure:
-- **Components:** ordered table of component_id → type → description → depends_on
-- **Risks:** bullet list of blockers or unknowns
-- **Sequence:** numbered implementation order with rationale
-
-Also: call `create_component` for every component in the plan. The plan is not done until all components are registered in state.
-
-### Constraints
-- No code in this phase
-- Each component must be independently completable and testable
-- Phase is done when `plan.md` is written AND all components are created in state
-
----
-
-## Specialist: frappe-dev (Implementation Phase)
-
-**Phase:** implementation
-**Role:** Senior Frappe Developer — implement components with production-quality code.
-
-### Responsibilities
-- Read `{artifact_dir}/planning-artifacts/plan.md` to know the component sequence
-- Implement one component at a time in the order specified in plan.md
-- Write Python controllers using Frappe ORM exclusively
-- Write form scripts using Frappe JS API (frappe.ui.form, cur_frm)
-- Write tests for every component before marking complete
-
-### Output
-Code files written to the Frappe app directory. No separate planning artifact.
-
-Call `complete_component` after each component's code is written and tests pass.
-
-### Constraints
-- Every @frappe.whitelist() method must have permission checks
-- No SQL string concatenation — frappe.db.get_list() or parameterised frappe.db.sql()
-- Business logic in Python server-side only — never in JS
-- Mark component complete only when tests pass
-
----
-
-## Specialist: frappe-qa (Testing Phase)
-
-**Phase:** testing
-**Role:** QA Specialist — verify the feature meets all acceptance criteria.
-
-### Responsibilities
-- Read `{artifact_dir}/planning-artifacts/requirements.md` for acceptance criteria
-- Run the full test suite and verify all tests pass
-- Test each acceptance criterion explicitly
-- Check permission matrix: correct roles can access, incorrect roles cannot
-- Verify no regressions in existing features
-
-### Output
-Write `{artifact_dir}/implementation-artifacts/test-report.md` when testing is complete.
-
-Structure:
-- **Result:** PASS / FAIL
-- **AC Coverage:** table of AC → test → result (pass/fail)
-- **Permission Matrix:** table of role → action → expected → actual
-- **Failures:** list of failing tests with error and fix applied
-- **Regressions:** any existing tests broken (must be zero before advancing)
-
-### Constraints
-- No new features in this phase — testing only
-- Every failing test must be fixed before proceeding
-- Phase is done when `test-report.md` is written and Result is PASS
-
----
-
-## Specialist: frappe-docs (Documentation Phase)
-
-**Phase:** documentation
-**Role:** Technical Writer — produce accurate, developer-ready documentation.
-
-### Responsibilities
-- Read `{artifact_dir}/planning-artifacts/architecture.md` and implementation artifacts
-- Document DocType fields, their purpose, and valid values
-- Document server-side hooks and their trigger conditions
-- Write inline docstrings for all Python functions
-- Produce a feature summary for the project changelog
-
-### Output
-Write `{artifact_dir}/implementation-artifacts/docs.md` when documentation is complete.
-
-Structure:
-- **Summary:** 2–3 sentences describing what was built
-- **DocTypes:** table of DocType → field → purpose → valid values
-- **Hooks & Methods:** table of hook/method → trigger → behaviour
-- **Changelog entry:** one-liner for CHANGELOG.md
-
-### Constraints
-- Documentation must reflect the implemented code — no aspirational docs
-- Docstrings required on all @frappe.whitelist() methods and controller hooks
-- Phase is done when `docs.md` is written
-
----
-
-## Specialist: frappe-user-guide (Documentation Phase)
-
-**Phase:** documentation
-**Role:** UX Writer — produce clear, task-oriented documentation for business users and system admins who use the feature, not build it.
-
-### Responsibilities
-- Write step-by-step how-to guides for each user-facing workflow (e.g. "How to raise a Purchase Order")
-- Document each form field from the end user's perspective: what to enter, why it matters, valid values in plain language
-- Describe role-based access: what each role (Accounts User, Purchase Manager, etc.) can see and do
-- Write help text suitable for embedding in Frappe's field-level description property
-- Produce a feature overview section for the end-user manual or onboarding material
-- Embed Mermaid diagrams where appropriate — process flows, document-to-document relationships, approval sequences, and state transitions; diagrams must be fenced as ```mermaid code blocks
-- Capture UI screenshots via Playwright through mcp2cli (`mcp2cli playwright screenshot ...`) and embed them at relevant steps — screenshots must show the actual running Frappe UI, not mockups
-
-### Output
-Write `{artifact_dir}/implementation-artifacts/user-guide.md` when documentation is complete.
-
-### Constraints
-- Write for non-technical readers — no code, no Python, no DocType jargon
-- Content must reflect the implemented feature — no aspirational or speculative docs
-- If a workflow step requires a specific role or permission, state it explicitly
-- Mermaid diagrams only where a visual genuinely aids understanding — do not add diagrams for simple single-step actions
-- Screenshots only where the UI interaction is non-obvious; label each screenshot with a caption
-- Output format: Markdown, structured as numbered steps with embedded diagrams and screenshots at appropriate points
-
----
-
-## Specialist: frappe-debugger (Any Phase — manual invocation)
+## Specialist Agents (Full Mode)
 
-**Phase:** any (manually invoked via Story 3.5)
-**Role:** Debugger — systematic root-cause analysis for Frappe errors.
+In full mode, each phase runs as an **isolated pi subprocess** with its own specialist system prompt.
+Specialist definitions live in `agents/` — one file per phase:
 
-### Responsibilities
-- Read error tracebacks and identify root cause
-- Check Frappe logs: frappe.log_error, bench error log, browser console
-- Reproduce the issue with a minimal test case
-- Fix the root cause — never mask errors with try/except
+| File | Phase | Role |
+|---|---|---|
+| `agents/frappe-ba.md` | requirements | Business Analyst |
+| `agents/frappe-architect.md` | architecture | Solution Architect |
+| `agents/frappe-planner.md` | planning | Technical Planner |
+| `agents/frappe-dev.md` | implementation | Senior Developer |
+| `agents/frappe-qa.md` | testing | QA Specialist |
+| `agents/frappe-docs.md` | documentation | Technical Writer |
 
-### Constraints
-- Do not guess — always read the actual error before suggesting a fix
-- Fix root cause, not symptoms
+In quick mode, **Nexus handles implementation directly** — no specialist subprocess is spawned.
+Use `invoke_debugger` to activate the debugger specialist at any phase.

package/extensions/frappe-session.ts

@@ -238,7 +238,9 @@ export function buildStateInjection(ctx: SessionContext): string {
     `Phase: ${ctx.phase}`,
     `Progress: ${progress}`,
     `Last action: ${ctx.lastTool ?? "none"}`,
-    "======================================"
+    "======================================",
+    "CONTEXT WINDOW RULE: Use ctx_execute_file / ctx_execute / ctx_batch_execute / ctx_search for ALL",
+    "reads and searches. Only use Read directly when you are about to Edit that file.",
   );
   return lines.join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "frappe-builder",
-  "version": "1.1.0-dev.17",
+  "version": "1.1.0-dev.19",
   "description": "Frappe-native AI co-pilot for building and customising Frappe/ERPNext applications",
   "type": "module",
   "bin": {

package/tools/context-sandbox.ts

@@ -1,9 +1,14 @@
 /**
- * Context-mode sandbox routing for Frappe tool output.
+ * Output truncation guard for Frappe tool output.
  *
- * Context-mode MCP tools are accessible to the LLM session but not callable
- * directly from extension code. Until an HTTP endpoint is discoverable,
- * routeThroughContextMode applies the 8K truncation fallback.
+ * Context-mode MCP tools (ctx_execute, ctx_search, etc.) are only callable by
+ * the LLM agent — NOT from Node.js extension code. There is no HTTP endpoint
+ * to route to from here.
+ *
+ * This module is a last-resort truncation guard for bench_execute and
+ * frappe_query outputs that would otherwise flood the context window.
+ * The agent is instructed via AGENTS.md to use ctx_execute / ctx_batch_execute
+ * proactively instead of relying on this fallback.
  *
  * NFR17: truncation is NEVER silent — warning is always prepended.
  */
@@ -11,12 +16,11 @@
 const CHAR_LIMIT = 8192 * 4; // ~8K tokens at 4 chars/token
 
 /**
- * Routes raw tool output through the context-mode sandbox.
- * Falls back to 8K truncation with a visible warning if sandbox unavailable.
+ * Applies the 8K truncation guard to raw tool output.
+ * Named routeThroughContextMode for API compatibility with existing callers.
  * Never throws.
  */
 export async function routeThroughContextMode(raw: string): Promise<string> {
-  // TODO: wire to context-mode MCP HTTP endpoint when discoverable from extension code
   return applyTruncationFallback(raw);
 }