From 342871e85e8746d2523f81ba4a8291605fdf3b71 Mon Sep 17 00:00:00 2001 From: Mikael Hugo Date: Tue, 5 May 2026 00:06:57 +0200 Subject: [PATCH] docs: clarify guided planning artifacts --- BUILD_PLAN_MILESTONE_MAP.md | 65 +++++++------------ .../sf/prompts/guided-discuss-project.md | 2 +- .../sf/prompts/guided-discuss-requirements.md | 2 +- .../sf/prompts/guided-research-project.md | 14 ++-- 4 files changed, 35 insertions(+), 48 deletions(-) diff --git a/BUILD_PLAN_MILESTONE_MAP.md b/BUILD_PLAN_MILESTONE_MAP.md index a69007c41..389c7b336 100644 --- a/BUILD_PLAN_MILESTONE_MAP.md +++ b/BUILD_PLAN_MILESTONE_MAP.md @@ -1,58 +1,38 @@ # BUILD_PLAN → Milestone Map -Every BUILD_PLAN.md tier item mapped to an existing or needed milestone. Items without milestones are gaps that must be resolved before v3 planning is complete. - -**Rule**: Every new milestone must cite which BUILD_PLAN tier/item it implements (D015). +Every BUILD_PLAN.md tier item mapped to a milestone. **Rule D015**: every new milestone must cite which BUILD_PLAN tier/item it implements. --- ## Tier 0 — Pi-mono ports → **M006** - -| Item | Status | -|---|---| -| HTML export escape | ✅ `701ec8fb8` | -| Empty tools array fix | ✅ `58b1d7c60` | -| Anthropic SSE unknown events | DEFERRED | -| Long local-LLM SSE timeout | ✅ `d0907b6d8` | -| Bedrock inference profile | ✅ `7c487bb60` | -| Symlinked packages dedup | TODO | -| ctx.ui.setWorkingVisible() | TODO | -| Cloudflare Workers AI | TODO | -| Azure Cognitive Services | TODO | -| Custom Anthropic SSE parser | TODO | - ## Tier 0.5 — gsd-2 ports → **M006 + M007** -17 items total, all mapped to M006 (critical fixes) or M007 (features). See BUILD_PLAN.md for full list. +All mapped. See BUILD_PLAN.md for item-level status. -## Tier 1 — ESSENTIAL → **GAP: no milestones** +## Tier 1 — ESSENTIAL → **ALL MAPPED** -| Item | Action | -|---|---| -| 1.1 Vault secret resolver | Create milestone | -| 1.2 Singularity Memory integration | Create milestone | -| 1.3 Schema reconciliation | Fold into M013 or create milestone | -| 1.4 Config schema alignment | Fold into M013 or create milestone | +| Item | Milestone | Slice | Status | +|---|---|---|---| +| 1.1 Vault secret resolver | **M017-yf67h6** | S01-S03 | ⬜ NEW | +| 1.2 Singularity Memory integration | **M017-jpw5jo** | S01-S03 | ⬜ NEW | +| 1.3 Schema reconciliation (spec rewrite) | **M013** | S12 | ⬜ Folded in | +| 1.4 Config schema alignment | **M013** | S13 | ⬜ Folded in | ## Tier 2 — STRONG → **ALL MAPPED** -| Item | Milestone | Slice | References BUILD_PLAN | +| Item | Milestone | Slice | Status | |---|---|---|---| -| 2.1 Persistent agents v1 | M012 | S01-S05 | ✅ | -| 2.2 Doc-sync sub-step | M009 | S08 | ✅ | -| 2.3 Intent chapters | M013 | S08 | ✅ | -| 2.4 PhaseReview 3-pass | M016 | S01-S02 | ✅ | -| 2.5 turn_status marker | M013 | S09 | ✅ | -| 2.6 last_error cap | M013 | S10 | ✅ | -| 2.7 cost_micro_usd | M013 | S11 | ✅ | +| 2.1 Persistent agents v1 | M012 | S01-S05 | ⬜ | +| 2.2 Doc-sync sub-step | M009 | S08 | ⬜ | +| 2.3 Intent chapters | M013 | S08 | ⬜ | +| 2.4 PhaseReview 3-pass | M016 | S01-S02 | ⬜ | +| 2.5 turn_status marker | M013 | S09 | ⬜ | +| 2.6 last_error cap | M013 | S10 | ⬜ | +| 2.7 cost_micro_usd | M013 | S11 | ⬜ | -## Tier 3 — NICE → **Deferred by design** +## Tier 3+ → **Deferred by design** -No milestones until Tier 2 completes. - -## Tier 4 — DEFER → **Deferred by design** - -No milestones until a deployment demands it. +--- ## Summary @@ -60,7 +40,8 @@ No milestones until a deployment demands it. |---|---|---| | Tier 0 | 10 (M006) | 0 | | Tier 0.5 | 17 (M006+M007) | 0 | -| **Tier 1** | **0** | **4 — need milestones** | +| **Tier 1** | **4** (M017×2, M013×2) | **0** | | Tier 2 | 7 (M012, M009, M013, M016) | 0 | -| Tier 3 | 0 | deferred | -| Tier 4 | 0 | deferred | +| Tier 3+ | 0 | deferred | + +**Zero gaps.** Every BUILD_PLAN tier item is either mapped to a milestone or explicitly deferred. diff --git a/src/resources/extensions/sf/prompts/guided-discuss-project.md b/src/resources/extensions/sf/prompts/guided-discuss-project.md index ceda04569..3a759119d 100644 --- a/src/resources/extensions/sf/prompts/guided-discuss-project.md +++ b/src/resources/extensions/sf/prompts/guided-discuss-project.md @@ -1,6 +1,6 @@ **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. For `.sf` files in this prompt, use absolute paths rooted at `{{workingDirectory}}` instead of discovering them with `Glob`. -Discuss the **project** as a whole. Identify gray areas at the project level — vision, users, anti-goals, key constraints — ask the user about them, and write `.sf/PROJECT.md` with the decisions. Use the **Project** output template below. If a `SF Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules. +Discuss the **project** as a whole. Identify gray areas at the project level — vision, users, anti-goals, key constraints — ask the user about them, and produce `.sf/PROJECT.md` with the decisions via `sf_summary_save`. Use the **Project** output template below. If a `SF Skill Preferences` block is present in system context, use it to decide which skills to load and follow; do not override required artifact rules. This stage runs ONCE per project, before any milestone-level discussion. It produces the project-level context that all subsequent milestones, requirements, and roadmaps will reference. diff --git a/src/resources/extensions/sf/prompts/guided-discuss-requirements.md b/src/resources/extensions/sf/prompts/guided-discuss-requirements.md index a7caa19bd..537a1dc8e 100644 --- a/src/resources/extensions/sf/prompts/guided-discuss-requirements.md +++ b/src/resources/extensions/sf/prompts/guided-discuss-requirements.md @@ -1,6 +1,6 @@ **Working directory:** `{{workingDirectory}}`. All file reads, writes, and shell commands MUST operate relative to this directory. Do NOT `cd` to any other directory. For `.sf` files in this prompt, use absolute paths rooted at `{{workingDirectory}}` instead of discovering them with `Glob`. -Discuss **project-level requirements**. Read `.sf/PROJECT.md` first — it is the authoritative source for vision, core value, anti-goals, and milestone sequence. All requirements must trace back to it. Identify gray areas about what capabilities the project must deliver, ask the user, and write `.sf/REQUIREMENTS.md` using the v2 structured `R###` format. Use the **Requirements** output template below. +Discuss **project-level requirements**. Read `.sf/PROJECT.md` first — it is the authoritative source for vision, core value, anti-goals, and milestone sequence. All requirements must trace back to it. Identify gray areas about what capabilities the project must deliver, ask the user, and produce `.sf/REQUIREMENTS.md` via `sf_summary_save` using the v2 structured `R###` format. Use the **Requirements** output template below. This stage runs ONCE per project, after `discuss-project` and before any milestone-level work. It produces the explicit capability contract that all milestones, slices, and verification will reference. diff --git a/src/resources/extensions/sf/prompts/guided-research-project.md b/src/resources/extensions/sf/prompts/guided-research-project.md index 144c6bf14..9d20f9df9 100644 --- a/src/resources/extensions/sf/prompts/guided-research-project.md +++ b/src/resources/extensions/sf/prompts/guided-research-project.md @@ -40,7 +40,7 @@ Prompt: > > Constraints from PROJECT.md: [list any tech constraints / required frameworks the user already specified]. > -> Deliverable: `.sf/research/STACK.md` with sections: +> Working file: `.sf/research/STACK.md` with sections: > - **Recommended Stack** (with versions and rationale) > - **Alternatives Considered** (and why not) > - **What NOT to use** (and why) @@ -58,13 +58,15 @@ Prompt: > > Active requirements from REQUIREMENTS.md to cross-check: [list R### IDs and titles]. > -> Deliverable: `.sf/research/FEATURES.md` with sections per category (Authentication, Content, Notifications, etc.): +> Working file: `.sf/research/FEATURES.md` with sections per category (Authentication, Content, Notifications, etc.): > - **Table stakes** — bullet list of expected capabilities, with one-sentence justification each > - **Differentiators** — bullet list of optional capabilities > - **Anti-features** — what successful [domain] products explicitly avoid > - **Cross-check vs REQUIREMENTS.md** — which active requirements are covered, which features are missing from REQUIREMENTS, which REQUIREMENTS look excessive > > Use web search to surface 3–5 representative competitors / examples in the space. Don't go deep — aim for coverage breadth. +> +> *(Note: `.sf/research/` files are transient working state used during planning. They inform the roadmap but are not promoted to docs/.)* ### Task 3 — Architecture research → `.sf/research/ARCHITECTURE.md` @@ -74,7 +76,7 @@ Prompt: > > Vision/scale signals from PROJECT.md: [extract scale-relevant phrases — solo / small team / enterprise / planned user count]. > -> Deliverable: `.sf/research/ARCHITECTURE.md` with sections: +> Working file: `.sf/research/ARCHITECTURE.md` with sections: > - **Recommended Architecture** — diagram-friendly description (data flow, services, key boundaries) > - **Data Model Sketch** — core entities, relationships, where state lives > - **Integration Points** — external services typically required (auth, payments, email, etc.) @@ -82,6 +84,8 @@ Prompt: > - **Reversibility risk** — which architectural choices are hardest to walk back later > > Use `resolve_library` for library-specific architecture docs. Mark confidence per recommendation. +> +> *(Note: `.sf/research/` files are transient working state used during planning. They inform the roadmap but are not promoted to docs/.)* ### Task 4 — Pitfalls research → `.sf/research/PITFALLS.md` @@ -91,7 +95,7 @@ Prompt: > > Project type from PROJECT.md: [greenfield / brownfield / migration]. > -> Deliverable: `.sf/research/PITFALLS.md` with sections: +> Working file: `.sf/research/PITFALLS.md` with sections: > - **Domain Pitfalls** — failure modes specific to this domain (e.g., for auth: session fixation, password reset flows, token rotation) > - **Stack Pitfalls** — known footguns of the recommended stack from STACK.md (or domain norm if STACK isn't ready) > - **Scope Traps** — features that look small but are huge ("just add notifications", "just add search") @@ -99,6 +103,8 @@ Prompt: > - **Migration pitfalls** (only if brownfield) — common breakage when retrofitting [domain] capability into existing systems > > Web search for postmortems, incident reports, and "lessons learned" content. Sources matter — prefer specific writeups over generic listicles. +> +> *(Note: `.sf/research/` files are transient working state used during planning. They inform the roadmap but are not promoted to docs/.)* ---