singularity/singularity-forge
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 2

docs: clarify guided planning artifacts

Browse source
This commit is contained in:
Mikael Hugo 2026-05-05 00:06:57 +02:00
parent 959e15ef42
commit 342871e85e
4 changed files with 35 additions and 48 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

65
BUILD_PLAN_MILESTONE_MAP.md
View file

@ -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.

2
src/resources/extensions/sf/prompts/guided-discuss-project.md
View file

@ -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.

2
src/resources/extensions/sf/prompts/guided-discuss-requirements.md
View file

@ -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.

14
src/resources/extensions/sf/prompts/guided-research-project.md
View file

@ -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/.)*
---