From e67e02947f2360726b17a1db8b2da45008a48cd2 Mon Sep 17 00:00:00 2001 From: can1357 Date: Sat, 31 Jan 2026 15:45:00 +0100 Subject: [PATCH] docs(coding-agent/prompts): added phased execution guidance for migrations and refactors with WASM to N-API example - Added phased execution guidance for migrations and refactors to prevent parallel work on dependent layers. - Added example demonstrating phased execution pattern for porting WASM to N-API with sequential foundation, parallel implementation, integration, and dependent layer phases. --- packages/coding-agent/CHANGELOG.md | 6 +++ .../coding-agent/src/prompts/tools/task.md | 54 +++++++++++++++++++ 2 files changed, 60 insertions(+) diff --git a/packages/coding-agent/CHANGELOG.md b/packages/coding-agent/CHANGELOG.md index abdd10f45..11aa837ae 100644 --- a/packages/coding-agent/CHANGELOG.md +++ b/packages/coding-agent/CHANGELOG.md @@ -1,6 +1,12 @@ # Changelog ## [Unreleased] + +### Added + +- Added phased execution guidance for migrations and refactors to prevent parallel work on dependent layers +- Added example demonstrating phased execution pattern for porting WASM to N-API with sequential foundation, parallel implementation, integration, and dependent layer phases + ### Removed - Removed Nushell language server configuration from LSP defaults diff --git a/packages/coding-agent/src/prompts/tools/task.md b/packages/coding-agent/src/prompts/tools/task.md index 42459dc2a..b135fe491 100644 --- a/packages/coding-agent/src/prompts/tools/task.md +++ b/packages/coding-agent/src/prompts/tools/task.md @@ -18,6 +18,27 @@ Agents with `output="structured"` enforce their own schema; the `schema` paramet **Never describe expected output in `context` or task descriptions.** All response format requirements go in the `schema` parameter. Use structured schemas with typed properties—not `{ "type": "string" }`. Prose like "respond as a bullet list" is prohibited. + +## Phased execution for migrations and refactors + +When work has layers where one layer must exist before the next can be built: + +1. **Foundation phase** — Create scaffolding, define interfaces, establish the API shape. Do this yourself or in a single task. Never fan out until the contract is known. +2. **Parallel implementation** — Fan out to independent tasks that all consume the same known interface. +3. **Integration phase** — Wire things together, update build/CI. Do this yourself. +4. **Dependent layer** — Fan out again for work that consumes the previous layer. + +**Wrong:** Launch "create Rust API" + "update JS bindings to use Rust API" + "update CI for Rust" in parallel. JS bindings need to know the API. CI needs to know what's being built. + +**Right:** +1. Create Rust API scaffold yourself (or single task) +2. Fan out: one task per module to implement against the scaffold +3. Update CI yourself +4. Fan out: one task per JS binding now that Rust exports are known + +The test: Can subagent B write correct code without seeing A's output? If no, they are sequential. + + {{#list agents join="\n"}} @@ -81,6 +102,39 @@ assistant: Uses the Task tool: } + +user: "Port the natives package from WASM to N-API" +assistant: This requires phased execution—JS bindings depend on knowing the Rust API. + +Phase 1: I'll create the N-API scaffold myself to establish the API shape. +assistant: [Uses Edit tool to create Cargo.toml with napi-rs, writes lib.rs with module structure and exported function signatures] + +Phase 2: Now that the API contract is defined, I'll fan out to implement each module. +assistant: Uses the Task tool: +{ + "agent": "task", + "context": "Implementing N-API native module. Scaffold exists at crates/pi-natives with napi-rs setup.\n\nAPI contract (from lib.rs):\n- grep: async fn search(pattern: &str, path: &str, opts: SearchOptions) -> Vec\n- text: fn visible_width(s: &str) -> usize, fn truncate(s: &str, width: usize) -> String\n- html: fn to_markdown(html: &str) -> String\n- image: fn resize(data: &[u8], width: u32, height: u32) -> Vec\n\nTask: Implement {{module}} module. File: crates/pi-natives/src/{{module}}.rs", + "schema": { "properties": { "exports": { "elements": { "type": "string" } }, "notes": { "type": "string" } } }, + "tasks": [ + { "id": "Grep", "description": "Implement parallel grep with ignore crate", "args": { "module": "grep" } }, + { "id": "Text", "description": "Implement text width/truncate", "args": { "module": "text" } }, + { "id": "Html", "description": "Implement HTML to markdown", "args": { "module": "html" } }, + { "id": "Image", "description": "Implement image resize", "args": { "module": "image" } } + ] +} + +Phase 3: Rust implementation complete. I'll update CI for native builds myself. +assistant: [Uses Edit tool to update .github/workflows/ci.yml with cross-platform native build matrix] + +Phase 4: Now I'll fan out to update JS bindings—the Rust exports are known. +assistant: Uses the Task tool: +{ + "agent": "task", + "context": "Update JS bindings to load N-API addon instead of WASM workers.\n\nRust exports (from Phase 2):\n{{exports}}\n\nTask: Update packages/natives/src/{{module}}/index.ts to use native addon. Remove worker.ts usage.", + ... +} + + - Describing response format in `context` (e.g., "respond as JSON", "return a bullet list")—use `schema` parameter instead - Confirmation bias: ask for factual discovery instead of yes/no exploration prompts