codeforge-dev 1.9.0 → 1.11.0

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/SKILL.md

@@ -5,14 +5,14 @@ description: >-
   "set up specs", "bootstrap specs", "start using specs", "create spec
   directory", "init specs for this project", or needs to set up the
   .specs/ directory structure for a project that doesn't have one yet.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Initialize Specification Directory
 
 ## Mental Model
 
-Before any spec can be created, the project needs a `.specs/` directory with its supporting files: a ROADMAP (what each version delivers) and a BACKLOG (deferred items). This skill bootstraps that structure so `/spec-new` has a home.
+Before any spec can be created, the project needs a `.specs/` directory with its supporting files: a MILESTONES tracker (what each milestone delivers) and a BACKLOG (deferred items). This skill bootstraps that structure so `/spec-new` has a home.
 
 ---
 
@@ -25,7 +25,7 @@ Glob: .specs/**/*.md
 ```
 
 **If `.specs/` already exists:**
-- Report current state: how many specs, versions, whether ROADMAP.md and BACKLOG.md exist
+- Report current state: how many specs, domains, whether MILESTONES.md and BACKLOG.md exist
 - Suggest `/spec-check` to audit health instead
 - Do NOT recreate or overwrite anything
 - Stop here
@@ -36,9 +36,9 @@ Glob: .specs/**/*.md
 
 Create the `.specs/` directory at the project root.
 
-### Step 3: Create ROADMAP.md
+### Step 3: Create MILESTONES.md
 
-Write `.specs/ROADMAP.md` using the template from `references/roadmap-template.md`.
+Write `.specs/MILESTONES.md` using the template from `references/milestones-template.md`.
 
 ### Step 4: Create BACKLOG.md
 
@@ -63,29 +63,32 @@ Summarize what was created:
 
 Created:
 - `.specs/` directory
-- `.specs/ROADMAP.md` — version tracking table
+- `.specs/MILESTONES.md` — milestone tracker
 - `.specs/BACKLOG.md` — deferred items list
 
 Next steps:
-- Use `/spec-new <feature-name> <version>` to create your first feature spec
+- Add features to `BACKLOG.md` with priority grades (P0–P3)
+- Pull features into a milestone in `MILESTONES.md` when ready to scope
+- Use `/spec-new <feature-name>` to create a spec (domain is inferred)
+- Use `/spec-refine <feature-name>` to validate before implementation
+- After implementing, use `/spec-review <feature-name>` to verify against the spec
+- Then use `/spec-update` to close the loop
 - Use `/spec-check` to audit spec health at any time
 ```
 
 ---
 
-## Hard Constraints
+## Constraints
 
 - **Never overwrite** an existing `.specs/` directory or its contents.
-- **ROADMAP.md** must stay under 30 lines (it's a summary, not a plan document).
-- **BACKLOG.md** must stay under 15 lines (it grows as items are added).
-- Templates are starting points — the user will extend them.
+- Templates are starting points — the user will extend them as the project grows.
 
 ---
 
 ## Ambiguity Policy
 
 - If the user runs this in a workspace root with multiple projects, ask which project to initialize.
-- If `.specs/` exists but is missing ROADMAP.md or BACKLOG.md, offer to create only the missing files.
+- If `.specs/` exists but is missing MILESTONES.md or BACKLOG.md, offer to create only the missing files.
 
 ---
 
@@ -93,5 +96,5 @@ Next steps:
 
 | File | Contents |
 |------|----------|
-| `references/roadmap-template.md` | Starter ROADMAP with version table format |
+| `references/milestones-template.md` | Starter MILESTONES with milestone table format |
 | `references/backlog-template.md` | Starter BACKLOG with item format |

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/backlog-template.md

@@ -1,7 +1,23 @@
 # Backlog
 
-Deferred items not yet scheduled for a version.
+Priority-graded feature and infrastructure backlog. Items are pulled into milestones when ready to scope and spec. See `MILESTONES.md` for the milestone workflow.
 
-## Items
+## P0 — High Priority
 
-- [ ] [Item description] — [context/rationale]
+- [ ] [Feature] — [Description]
+
+## P1 — Important
+
+- [ ] [Feature] — [Description]
+
+## P2 — Desired
+
+- [ ] [Feature] — [Description]
+
+## P3 — Nice to Have
+
+- [ ] [Feature] — [Description]
+
+## Infrastructure & CI
+
+- [ ] [Item] — [Description]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-init/references/milestones-template.md

@@ -0,0 +1,32 @@
+# Milestones
+
+> Features are organized by domain in `.specs/`. Milestones group features
+> into deliverable increments. See `BACKLOG.md` for the feature backlog.
+
+## How Milestones Work
+
+1. **Backlog** — All desired features live in `BACKLOG.md`, graded by priority.
+2. **Milestone scoping** — When ready to plan a deliverable, pull features from the backlog.
+3. **Spec first** — Each feature gets a spec (via `/spec-new`) before implementation begins.
+4. **Ship** — A milestone is done when all its specs are implemented and verified.
+
+Only the **current milestone** is defined in detail. Everything else is backlog.
+
+## Released
+
+_None yet._
+
+## Current
+
+### [Milestone Name]
+
+- [ ] `domain/feature-name.md` — [Brief description]
+- [ ] `domain/feature-name.md` — [Brief description]
+
+## Next
+
+> Scoped from `BACKLOG.md` when the current milestone is complete.
+
+## Out of Scope
+
+- [Items explicitly not planned]

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/SKILL.md

@@ -5,7 +5,7 @@ description: >-
   "new feature spec", "write a spec for", "spec this feature",
   "start a new spec", "plan a feature", or needs to create a new
   specification file from the standard template.
-version: 0.1.0
+version: 0.2.0
 ---
 
 # Create New Feature Specification
@@ -14,7 +14,7 @@ version: 0.1.0
 
 A specification is a contract between the person requesting a feature and the person building it. Writing the spec BEFORE implementation forces you to think through edge cases, acceptance criteria, and scope boundaries while changes are cheap — before any code exists.
 
-Every project uses `.specs/` as the specification directory. Specs are version-organized, independently loadable, and capped at 200 lines.
+Every project uses `.specs/` as the specification directory. Specs are domain-organized, independently loadable, and should aim for ~200 lines.
 
 ---
 
@@ -22,33 +22,35 @@ Every project uses `.specs/` as the specification directory. Specs are version-o
 
 ### Step 1: Parse Arguments
 
-Extract the feature name and version from `$ARGUMENTS`:
+Extract the feature name from `$ARGUMENTS`:
 - **Feature name**: kebab-case identifier (e.g., `session-history`, `auth-flow`)
-- **Version**: semver string (e.g., `v0.3.0`)
 
-If arguments are missing, ask the user for:
-1. Feature name (what is being built)
-2. Target version (which release this belongs to)
+If the feature name is missing, ask the user what they want to spec.
 
-### Step 2: Determine File Path
+**Note:** Features should be pulled from the project's backlog (`BACKLOG.md`) into a milestone before creating a spec. If the feature isn't in the backlog yet, add it first, then assign it to a milestone.
 
-- **Multi-feature version** (directory already exists or multiple features planned):
-  `.specs/{version}/{feature-name}.md`
-- **Single-feature version** (one spec covers the whole version):
-  `.specs/{version}.md`
+### Step 2: Determine Domain and File Path
+
+Analyze the feature name and description to infer an appropriate domain folder:
+- Look at existing domain folders in `.specs/` for a natural fit
+- Consider the feature's area: `auth`, `search`, `ui`, `api`, `onboarding`, etc.
+- Present the inferred domain to the user for confirmation or override
+
+The file path is always: `.specs/{domain}/{feature-name}.md`
 
 If `.specs/` does not exist at the project root, create it.
 
-If `.specs/{version}/` does not exist and you're using the directory form, create it.
+If `.specs/{domain}/` does not exist, create it.
 
 ### Step 3: Create the Spec File
 
 Write the file using the standard template from `references/template.md`.
 
 Pre-fill:
-- **Version**: from arguments
+- **Domain**: from the inferred/confirmed domain
 - **Status**: `planned`
 - **Last Updated**: today's date (YYYY-MM-DD)
+- **Approval**: `draft`
 - **Feature name**: from arguments
 
 Leave all other sections as placeholders for the user to fill.
@@ -62,24 +64,30 @@ After creating the file, guide the user through filling it out:
 3. **Key Files** — Glob the codebase to identify existing files relevant to this feature
 4. **Schema / Data Model** — Reference file paths only, never inline schemas
 5. **API Endpoints** — Table format: Method | Path | Description
-6. **Requirements** — EARS format, numbered FR-1, FR-2, NFR-1, etc.
+6. **Requirements** — EARS format, numbered FR-1, FR-2, NFR-1, etc. Tag all requirements `[assumed]` at creation time — they become `[user-approved]` only after explicit user validation via `/spec-refine`.
 7. **Dependencies** — What this feature depends on
 8. **Out of Scope** — Explicit non-goals to prevent scope creep
+9. **Resolved Questions** — Leave empty at creation; populated by `/spec-refine`
 
 ### Step 5: Validate
 
 Before finishing:
-- [ ] File is ≤200 lines
+- [ ] If the file exceeds ~200 lines, consider splitting into separate specs in the domain folder
 - [ ] No source code, SQL, or type definitions reproduced inline
-- [ ] Status is `planned`
+- [ ] Status is `planned` and Approval is `draft`
 - [ ] All required sections present (even if some are "N/A" or "TBD")
 - [ ] Acceptance criteria are testable
+- [ ] All requirements are tagged `[assumed]`
+
+After validation, inform the user: **"This spec MUST go through `/spec-refine` before implementation begins.** All requirements are marked `[assumed]` until explicitly validated."
+
+The `/spec-refine` skill walks through every `[assumed]` requirement with the user, validates tech decisions and scope boundaries, and upgrades approved items to `[user-approved]`. The spec's `**Approval:**` becomes `user-approved` only after all requirements pass review.
 
 ---
 
-## Hard Constraints
+## Sizing Guidelines
 
-- **≤200 lines per spec.** If a feature needs more, split into sub-specs with a parent `_overview.md` (≤50 lines) linking them.
+- **Aim for ~200 lines per spec.** If a feature needs more, consider splitting into separate specs in the domain folder.
 - **Reference, don't reproduce.** Write `see src/engine/db/migrations/002.sql lines 48-70` — never paste the SQL.
 - **Independently loadable.** Each spec file must be useful without loading any other file.
 - **EARS format for requirements.** Use the `specification-writing` skill for templates and examples.
@@ -88,7 +96,7 @@ Before finishing:
 
 ## Ambiguity Policy
 
-- If the user doesn't specify a version, ask — do not assume.
+- If the user doesn't specify a domain, infer one from the feature name and existing `.specs/` structure, then confirm with the user.
 - If the feature scope is unclear, write a minimal spec with `## Open Questions` listing what needs clarification.
 - If a spec already exists for this feature, inform the user and suggest `/spec-update` instead.
 

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-new/references/template.md

@@ -9,9 +9,10 @@ Standard template for all feature specifications. Copy this structure when creat
 ```markdown
 # Feature: [Name]
 
-**Version:** v0.X.0
+**Domain:** [domain-name]
 **Status:** planned
 **Last Updated:** YYYY-MM-DD
+**Approval:** draft
 
 ## Intent
 
@@ -21,6 +22,8 @@ Standard template for all feature specifications. Copy this structure when creat
 
 [Testable criteria. Use Given/When/Then for complex flows, checklists for simple features, or tables for business rules. Every criterion must be verifiable.]
 
+[Markers: `[ ]` = not started, `[~]` = implemented but not yet verified, `[x]` = verified (tests pass). During `/spec-build`, criteria progress from `[ ]` to `[~]` during implementation, then to `[x]` after review.]
+
 - [ ] [Criterion 1]
 - [ ] [Criterion 2]
 - [ ] [Criterion 3]
@@ -56,14 +59,14 @@ Standard template for all feature specifications. Copy this structure when creat
 
 ### Functional Requirements
 
-- FR-1: [EARS format requirement — see specification-writing skill for templates]
-- FR-2: When [event], the system shall [action].
-- FR-3: If [unwanted condition], then the system shall [action].
+- FR-1 [assumed]: [EARS format requirement — see specification-writing skill for templates]
+- FR-2 [assumed]: When [event], the system shall [action].
+- FR-3 [assumed]: If [unwanted condition], then the system shall [action].
 
 ### Non-Functional Requirements
 
-- NFR-1: The system shall respond to [endpoint] within [N]ms at the [percentile] percentile.
-- NFR-2: [Security, accessibility, scalability requirement]
+- NFR-1 [assumed]: The system shall respond to [endpoint] within [N]ms at the [percentile] percentile.
+- NFR-2 [assumed]: [Security, accessibility, scalability requirement]
 
 ## Dependencies
 
@@ -75,6 +78,10 @@ Standard template for all feature specifications. Copy this structure when creat
 - [Explicit non-goal 1 — prevents scope creep]
 - [Explicit non-goal 2]
 
+## Resolved Questions
+
+[Decisions explicitly approved by the user via `/spec-refine`. Each entry: decision topic, chosen option, date, brief rationale.]
+
 ## Implementation Notes
 
 [Post-implementation only. Leave empty in planned specs. After building, document what actually shipped vs. what was planned.]
@@ -108,3 +115,25 @@ Standard template for all feature specifications. Copy this structure when creat
 | `planned` | Spec written, implementation not started |
 | `partial` | Some acceptance criteria implemented, work ongoing |
 | `implemented` | All acceptance criteria met, as-built notes complete |
+
+## Approval Workflow
+
+| Tag | Meaning |
+|-----|---------|
+| `[assumed]` | Requirement was drafted by AI or inferred — treated as a hypothesis |
+| `[user-approved]` | Requirement was explicitly reviewed and approved by the user via `/spec-refine` |
+
+| Approval Status | Meaning |
+|-----------------|---------|
+| `draft` | Spec has unvalidated assumptions — NOT approved for implementation |
+| `user-approved` | All requirements are `[user-approved]` — ready for implementation |
+
+## Acceptance Criteria Markers
+
+| Marker | Meaning |
+|--------|---------|
+| `[ ]` | Not started |
+| `[~]` | Implemented, not yet verified — code written, tests not confirmed |
+| `[x]` | Verified — tests pass, behavior confirmed |
+
+**Workflow:** `/spec-new` creates → `/spec-refine` validates → `/spec-build` implements + closes the loop (or implement manually → `/spec-review` verifies → `/spec-update` closes the loop).

package/.devcontainer/plugins/devs-marketplace/plugins/code-directive/skills/spec-refine/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: spec-refine
+description: >-
+  This skill should be used when the user asks to "refine a spec",
+  "review spec assumptions", "validate spec decisions", "question the
+  spec", "iterate on the spec", "check spec for assumptions", "approve
+  the spec", "walk me through the spec", or needs iterative
+  user-driven refinement of a specification through structured
+  questioning rounds.
+version: 0.1.0
+---
+
+# Iterative Spec Refinement
+
+## Mental Model
+
+A draft spec is a hypothesis, not a commitment. Every requirement, tech decision, and scope boundary in a draft is an assumption until the user explicitly validates it. This skill systematically mines a spec for unvalidated assumptions, presents each to the user for review via structured questions, and iterates until every decision has explicit user approval.
+
+No implementation begins on a spec with `**Approval:** draft`. This skill is the gate.
+
+---
+
+## Workflow
+
+### Step 1: Load & Inventory
+
+Find the target spec:
+- If `$ARGUMENTS` contains a path or feature name, use it directly
+- Otherwise, glob `.specs/**/*.md` and ask the user which spec to refine
+
+Read the full spec. Catalog:
+- Every section and whether it has content
+- The `**Approval:**` status (should be `draft`)
+- All requirements and their current markers (`[assumed]` vs `[user-approved]`)
+- The `## Open Questions` section (if any)
+- The `## Resolved Questions` section (if any)
+
+If the spec is already `**Approval:** user-approved` and all requirements are `[user-approved]`, report this and ask if the user wants to re-review anyway.
+
+### Step 2: Assumption Mining
+
+Scan each section systematically for unvalidated decisions. Look for:
+
+| Category | What to look for |
+|----------|-----------------|
+| **Tech decisions** | Database choices, auth mechanisms, API formats, libraries, protocols |
+| **Scope boundaries** | What's included/excluded without stated rationale |
+| **Performance targets** | Numbers (response times, limits, thresholds) that were assumed |
+| **Architecture choices** | Where logic lives, service boundaries, data flow patterns |
+| **Behavioral defaults** | Error handling, retry logic, fallback behavior, timeout values |
+| **Unstated dependencies** | Systems, services, or libraries the spec assumes exist |
+| **Security assumptions** | Auth requirements, data sensitivity, access control patterns |
+
+For each assumption found, prepare a question with 2-4 alternatives including the current assumption.
+
+Present findings via `AskUserQuestion` in rounds of 1-4 questions. Group related assumptions together. Example:
+
+```
+Question: "Which authentication mechanism should this feature use?"
+Options:
+- JWT with refresh tokens (current assumption)
+- Session cookies with httpOnly flag
+- OAuth2 with external provider
+```
+
+Record each answer. After the user responds, check: did any answer reveal new assumptions or contradictions? If yes, add follow-up questions to the queue.
+
+### Step 3: Requirement Validation
+
+Walk through every requirement tagged `[assumed]`:
+
+1. **Read the requirement** aloud to the user (via the question text)
+2. **Assess** — is it specific? testable? complete?
+3. **Present via AskUserQuestion** with options:
+   - Approve as-is
+   - Needs revision (user provides direction via "Other")
+   - Remove (not needed)
+   - Defer to Open Questions (not decidable yet)
+
+Process requirements in batches of 1-4 per question round. Prioritize:
+- Requirements with the most ambiguity first
+- Requirements that other requirements depend on
+- Requirements involving tech decisions or external systems
+
+For approved requirements, update the marker from `[assumed]` to `[user-approved]`.
+For revised requirements, rewrite per user direction and mark `[user-approved]`.
+For removed requirements, delete them.
+For deferred requirements, move to `## Open Questions`.
+
+### Step 4: Acceptance Criteria Review
+
+For each acceptance criterion:
+1. Is it measurable and testable?
+2. Does it map to a specific requirement?
+3. Are there requirements without corresponding criteria?
+
+Present gaps to the user:
+- Missing criteria for existing requirements
+- Criteria that don't map to any requirement
+- Criteria with vague or unmeasurable outcomes
+
+Get approval on each criterion or batch of related criteria.
+
+### Step 5: Scope & Dependency Audit
+
+Review the spec from four perspectives:
+
+**User perspective:**
+- Does the feature solve the stated problem?
+- Are there user needs not addressed?
+- Is the scope too broad or too narrow?
+
+**Developer perspective:**
+- Is this implementable with the current architecture?
+- Are the key files accurate?
+- Are there missing technical constraints?
+
+**Security perspective:**
+- Are there data sensitivity issues?
+- Is authentication/authorization addressed?
+- Are there input validation gaps?
+
+**Operations perspective:**
+- Deployment considerations?
+- Monitoring and observability needs?
+- Rollback strategy needed?
+
+Surface any missing items via `AskUserQuestion`. Get explicit decisions on scope boundaries and dependency completeness.
+
+### Step 6: Final Approval
+
+1. Present a summary of all changes made during refinement:
+   - Assumptions resolved (count)
+   - Requirements approved/revised/removed
+   - New criteria added
+   - Scope changes
+
+2. Ask for final approval via `AskUserQuestion`:
+   - "Approve spec — all decisions validated, ready for implementation"
+   - "More refinement needed — specific concerns remain"
+
+3. On approval:
+   - Set `**Approval:** user-approved`
+   - Update `**Last Updated:**` to today
+   - Verify all requirements are tagged `[user-approved]`
+   - Populate `## Resolved Questions` with the decision trail from this session
+
+4. On "more refinement needed":
+   - Ask what concerns remain
+   - Loop back to the relevant phase
+
+---
+
+## Convergence Rules
+
+- After each phase, check: did answers from this phase raise new questions? If yes, run another questioning round before advancing.
+- The skill does NOT terminate until ALL of:
+  - Every `[assumed]` requirement is resolved (approved, revised, removed, or deferred)
+  - All acceptance criteria are reviewed
+  - The user gives explicit final approval
+- If the user wants to stop early, leave `**Approval:** draft` and note remaining items in `## Open Questions`.
+
+---
+
+## Resolved Questions Format
+
+Each resolved question follows this format:
+
+```markdown
+1. **[Decision topic]** — [Chosen option] (user-approved, YYYY-MM-DD)
+   - Options considered: [list]
+   - Rationale: [brief user reasoning or context]
+```
+
+Keep entries concise — decision + options + rationale in 2-3 lines each.
+
+---
+
+## Ambiguity Policy
+
+- If the spec has no `**Approval:**` field, treat it as `draft` and add the field.
+- If requirements lack `[assumed]`/`[user-approved]` tags, treat all as `[assumed]`.
+- If the user says "approve everything" without reviewing individual items, warn that blanket approval defeats the purpose — offer to fast-track by presenting summaries of each batch.
+- If the spec is very short (< 30 lines), the full 6-phase process may be unnecessary. Adapt: merge phases 2-4 into a single review pass. Still require explicit final approval.
+- If the user provides a feature name that matches multiple specs, list them and ask which to refine.
+
+---
+
+## Anti-Patterns
+
+- **Rubber-stamping**: Presenting assumptions and immediately suggesting "approve all." Every assumption gets its own question with real alternatives.
+- **Leading questions**: "Should we use JWT as planned?" is leading. Present alternatives neutrally: "Which auth mechanism should this feature use? Options: JWT, sessions, OAuth2."
+- **Skipping phases**: Every phase surfaces different types of assumptions. Don't skip phases even if earlier phases had few findings.
+- **Silent upgrades**: Never change `[assumed]` to `[user-approved]` without presenting the item to the user first.