@khanhspring/forge-spec 1.0.0 → 1.1.0

package/bin/install.js

@@ -2,12 +2,11 @@
 
 import { cpSync, mkdirSync } from 'fs';
 import { join, dirname } from 'path';
-import { homedir } from 'os';
 import { fileURLToPath } from 'url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = join(__dirname, '..');
-const SKILLS_DIR = join(homedir(), '.claude', 'skills');
+const SKILLS_DIR = join(process.cwd(), '.claude', 'skills');
 
 const SKILLS = [
   'forge-brainstorm',
@@ -25,9 +24,9 @@ console.log('Installing @forge-workflow/spec skills...\n');
 mkdirSync(SKILLS_DIR, { recursive: true });
 
 for (const skill of SKILLS) {
-  cpSync(join(ROOT, skill), join(SKILLS_DIR, skill), { recursive: true, force: true });
+  cpSync(join(ROOT, 'skills', skill), join(SKILLS_DIR, skill), { recursive: true, force: true });
   console.log(`  ✓ ${skill}`);
 }
 
-console.log(`\nInstalled to ${SKILLS_DIR}`);
+console.log(`\nInstalled to ${SKILLS_DIR} (project-local)`)
 console.log('Restart Claude Code, then run /forge-init in your spec repo.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhspring/forge-spec",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Forge spec repo skills for Claude Code — brainstorm, spec, tasks, contract, and more",
   "type": "module",
   "bin": {
@@ -8,14 +8,7 @@
   },
   "files": [
     "bin",
-    "forge-brainstorm",
-    "forge-close",
-    "forge-config",
-    "forge-contract",
-    "forge-init",
-    "forge-spec",
-    "forge-status",
-    "forge-tasks"
+    "skills"
   ],
   "keywords": ["claude-code", "skills", "ai", "workflow", "microservices"],
   "license": "MIT"

package/{forge-brainstorm → skills/forge-brainstorm}/SKILL.md

@@ -18,14 +18,40 @@ every unknown either resolved or explicitly accepted as an assumption.
 
 <HARD-GATE>
 Do NOT generate a spec, break down tasks, or write any contracts in this phase.
-The ONLY file this skill writes is `features/{slug}/brainstorm.md`, and only AFTER
-the user has explicitly approved the Brainstorm Summary at the gate (Step 7).
+The only files this skill writes are `features/{slug}/brainstorm.md` and one row in
+`features/CHANGELOG.md`, and only AFTER the user has explicitly approved the Brainstorm
+Summary at the gate (Step 7).
 "Simple" features are where unexamined assumptions cause the most wasted work — no feature
 skips this phase.
 </HARD-GATE>
 
 ---
 
+## Step 0 — Check for existing external context
+
+Before anything else, check if the user has provided external content to work from.
+Signals: they paste a block of text, mention "we have a Confluence page / Google Doc / proposal /
+PRD / design doc", or say "here's the draft".
+
+**If external content is present (pasted inline):**
+Extract everything you can from it — map it to the mandatory question areas in Step 2.
+Note what is covered, what is missing, and what is ambiguous.
+Report back:
+> "I've read your {doc type}. Here's what I extracted:
+> ✅ Covered: {list of areas — problem, actors, happy path, etc.}
+> ❓ Missing or unclear: {list of gaps}
+> ⚠️ Ambiguous: {anything that could be read two ways}
+>
+> I'll ask only about the gaps. Sound good?"
+
+**If the user mentions a doc but hasn't pasted it:**
+> "I can't access external URLs directly — could you paste the relevant content here?
+> Even a rough copy-paste is fine; I'll extract what I need."
+
+**If no external content** — proceed straight to Step 1.
+
+---
+
 ## Step 1 — Load & Research Context
 
 Before asking the user anything, research the existing codebase silently:
@@ -57,7 +83,8 @@ Then check scope:
 ## Step 2 — Mandatory questions (one at a time)
 
 These MUST all be answered before moving to Step 4. Ask one at a time.
-Skip any sub-question already answered by your research in Step 1.
+**Skip any area already covered by Step 0 extraction or Step 1 research.**
+Only ask about genuine gaps — never re-ask what the user already provided.
 
 **If a question hits an unknown** — something the user can't answer without researching —
 use the Research Flag pattern (see Research Handling below).
@@ -302,8 +329,17 @@ If (b), convert each item to an explicit assumption in the summary.
 
 ## Step 8 — Persist the summary (after approval only)
 
-Once the user says **yes**, write the approved summary to `features/{slug}/brainstorm.md`
-so it survives across sessions and forge-spec can pick it up later.
+Once the user says **yes**:
+
+**8a — Assign sequence number and ask about dependencies**
+
+Read `features/CHANGELOG.md`. Count existing rows to get the next `#`.
+
+Ask (one message):
+> "Does this feature depend on any other feature being shipped first?
+> _(Enter slugs like `user-registration`, or 'none')_"
+
+**8b — Write `features/{slug}/brainstorm.md`**
 
 ```markdown
 # Brainstorm: {Feature Name}
@@ -315,18 +351,26 @@ so it survives across sessions and forge-spec can pick it up later.
 {the full Brainstorm Summary body from Step 6 — all sections}
 ```
 
+**8c — Append row to `features/CHANGELOG.md`**
+
+Add a new row — status `Brainstormed`, modules left blank until forge-spec fills them:
+```
+| {n} | {slug} | {one-line from Problem section} | Brainstormed | — | {depends or —} |
+```
+
 Then hand off:
-> "Saved to `features/{slug}/brainstorm.md`. Run `/forge-spec {slug}` to write the spec."
+> "Saved to `features/{slug}/brainstorm.md` and added to the changelog as #{n}.
+> Run `/forge-spec {slug}` to write the spec."
 
 ---
 
 ## Rules
 - One question per message — never list multiple at once
 - Prefer multiple-choice when options are predictable
-- Never skip Step 2 mandatory areas — even for "simple" features
-- Never skip the challenge round (Step 4)
-- Never skip the approaches step (Step 5)
+- Cover all Step 2 mandatory areas — but fill from Step 0 extraction first; only ask for genuine gaps
+- Never skip the challenge round (Step 4) — even when a doc covers everything, challenge it
+- Never skip the approaches step (Step 5) — a doc may have a chosen approach but alternatives should still be surfaced
 - YAGNI: move anything non-core to Out of Scope
 - The ONLY file written is `features/{slug}/brainstorm.md`, and only after approval (Step 8)
 - Do NOT skip Step 1 research — always check existing context first
-- Do NOT ask questions that could be answered by reading the existing codebase
+- Do NOT ask questions that could be answered by reading the existing codebase or the pasted doc

package/{forge-close → skills/forge-close}/SKILL.md

@@ -93,6 +93,7 @@ Feature progress: {feature-slug}
 **If all modules are complete:**
 Update `features/{slug}/tasks.md` header status to `Done`
 and `features/{slug}/spec.md` header status to `Done`.
+Update `features/CHANGELOG.md`: find the row for `{slug}` and set `Status` → `Done`.
 
 > "🎉 All modules done — feature `{slug}` is complete."
 

package/{forge-contract → skills/forge-contract}/SKILL.md

@@ -28,7 +28,11 @@ and the user has explicitly confirmed it.
 - Feature slug from $ARGUMENTS, or ask: "Which feature do you want to generate a contract for?"
 - Read `features/{slug}/spec.md` — must exist, otherwise stop.
 - Read `features/{slug}/tasks.md` — must exist, otherwise say "Run `/forge-tasks {slug}` first."
-- Read `.forge/project.json` — get module names, ports, stacks.
+- Read `.forge/project.json` — build a flat list of **contract targets**:
+  - Module with no submodules → target name = `{module.name}`, contract path = `contracts/{module.name}/`
+  - Module with submodules → target name = each `{submodule.name}`, contract path = `contracts/{submodule.name}/`
+  - Submodules use their own name as the target — identical to a standalone module — so they can be
+    promoted to a separate repo later with no contract path changes.
 
 ---
 
@@ -207,6 +211,8 @@ Update the API Endpoints table in `features/{slug}/spec.md`:
 Also advance the spec status: change the `**Status:**` line in `features/{slug}/spec.md`
 from `Draft` to `Ready` (planning complete — ready for implementation).
 
+Update `features/CHANGELOG.md`: find the row for `{slug}` and set `Status` → `Ready`.
+
 ---
 
 ## Step 7 — Completion

package/{forge-init → skills/forge-init}/SKILL.md

@@ -53,16 +53,39 @@ For each module, ask these in order (one question per message):
 2. **Type** — "Is `{name}` a backend service, frontend app, or something else?
    _(backend / frontend / worker / gateway)_"
 3. **Stack** — "What's the tech stack for `{name}`? (e.g. `Spring Boot 3, Java 21` or `React, TypeScript`)"
-4. **Port** — "What port does `{name}` run on locally?"
-5. **Repo URL** — "What's the git repo URL for `{name}`?
+4. **Repo URL** — "What's the git repo URL for `{name}`?
    _(Skip with 'none' if not set up yet)_"
-6. **Description** — "One sentence: what does `{name}` do?
-   _(Skip with 'none')_"
-
-After collecting all fields for a module, confirm it back:
+5. **Submodules** — scan the user's answers so far for signals: words like "monorepo", "multi-module",
+   "Gradle modules", a comma-separated list of app names, etc.
+   **If signals present**, ask:
+   > "It sounds like `{name}` contains multiple submodules ({detected names if any}).
+   > Should I configure them separately? (yes / no)"
+   **If yes** → collect submodules one at a time (see below). Skip step 6 — port belongs to each submodule, not the parent.
+   **If no or no signals** → continue to step 6.
+6. **Port** _(skip when module has submodules)_ — "What port does `{name}` run on locally?"
+7. **Description** — "One sentence: what does `{name}` do? _(Skip with 'none')_"
+
+**Submodule collection** (repeat for each):
+- "Submodule name? (kebab-case)"
+- "Type? (backend / frontend / worker)"
+- "Stack?"
+- "Port?"
+- "Path within the `{name}` repo? (e.g. `apps/admin` or `auth-ui`)"
+- "One sentence: what does it do? _(Skip with 'none')_"
+
+Confirm each: "`{sub}` — {type} — {stack} — :{port} — path: {path}. Another submodule? (yes / no)"
+
+> **Rules for submodules:**
+> - No `repo` field — submodules share the parent module's repo
+> - No `port` on the parent module — port belongs to each submodule
+> - `type` and `stack` are per-submodule (may differ from the parent)
+
+After collecting all submodules (or just module fields), confirm:
 
 > "Got it:
-> `{name}` — {type} — {stack} — :{port} — {repo or 'no repo yet'}
+> `{name}` — {type} — {repo or 'no repo yet'}
+> {if no submodules: stack + port}
+> {if submodules: list each as `  ↳ {sub} — {type} — {stack} — :{port} — {path}`}
 > {description}
 > Is that right?"
 
@@ -112,7 +135,7 @@ CLAUDE.md
   Conventions: {list or "none yet"}
   Out of scope: {list or "none yet"}
 
-features/.gitkeep
+features/CHANGELOG.md
 contracts/.gitkeep
 .gitignore  ← append Forge entries
 ```
@@ -126,6 +149,8 @@ Wait for confirmation. Do not write anything before the user says yes.
 ## Phase 5 — Write files
 
 Write `.forge/project.json`:
+
+Module **without** submodules — `port` and `stack` on the module itself:
 ```json
 {
   "project": "{project-name}",
@@ -146,6 +171,35 @@ Write `.forge/project.json`:
 }
 ```
 
+Module **with** submodules — no `port` on the module; each submodule owns its `port`, `stack`,
+`type`, and `path`; no `repo` on submodules (they share the parent's repo):
+```json
+{
+  "project": "{project-name}",
+  "version": "1.0",
+  "modules": [
+    {
+      "name": "{module-name}",
+      "repo": "{repo-url}",
+      "description": "{description}",
+      "submodules": [
+        {
+          "name": "{sub-name}",
+          "type": "backend|frontend|worker",
+          "stack": ["{stack}"],
+          "port": {port},
+          "path": "{relative-path-in-repo}",
+          "description": "{description}"
+        }
+      ]
+    }
+  ],
+  "spec_repo": "{spec-repo-url}",
+  "contract_format": "openapi3",
+  "contract_tool": "specmatic"
+}
+```
+
 Write `CLAUDE.md`:
 ```markdown
 # {project-name}
@@ -157,6 +211,14 @@ Write `CLAUDE.md`:
 |------|------|-------|------|
 | {name} | {type} | {stack} | {port} |
 
+_(For modules with submodules, expand the table with one row per submodule.
+Indent the submodule name with `↳` and omit port/stack from the parent row.)_
+
+| Name | Type | Stack | Port | Path |
+|------|------|-------|------|------|
+| {module} | — | — | — | — |
+| ↳ {sub} | {type} | {stack} | {port} | {path} |
+
 ## Forge Workflow
 1. `/forge-brainstorm` — explore and define a feature
 2. `/forge-spec`       — write the spec
@@ -182,8 +244,18 @@ Utilities: `/forge-status` (feature dashboard) · `/forge-config` (edit modules/
 - `contracts/{module}/{slug}.yaml` + `schemas/` + `shared/` — Specmatic OpenAPI 3.0 contracts
 ```
 
+Create `features/CHANGELOG.md`:
+```markdown
+# Feature Changelog
+
+Ordered list of all features. Add entries via `/forge-brainstorm`; update via `/forge-spec`,
+`/forge-contract`, and `/forge-close`. Use `Depends on` to declare what must ship first.
+
+| # | Slug | Description | Status | Modules | Depends on |
+|---|------|-------------|--------|---------|------------|
+```
+
 Create:
-- `features/.gitkeep`
 - `contracts/.gitkeep`
 
 Append to `.gitignore` if not present:
@@ -202,4 +274,8 @@ Run `git status` and confirm:
 - Never write files before the user says yes in Phase 4
 - Never overwrite existing files
 - All written files must be complete — no unfilled placeholders
+- **Extract, don't re-ask**: if the user's answer contains information for upcoming fields
+  (e.g. "user-service, Spring Boot 3, port 8080, backend"), extract and fill those fields
+  silently — only ask about what is genuinely missing. Never ask a question the user has
+  already answered, even indirectly.
 - If the user provides multiple answers in one message, accept them gracefully and move forward

package/{forge-spec → skills/forge-spec}/SKILL.md

@@ -270,9 +270,16 @@ Cross-module data: {what is shared with or derived from other modules — or "No
 
 ---
 
-## Step 7 — Gate
+## Step 7 — Update changelog & gate
 
-After writing, say:
+After writing `spec.md`, update `features/CHANGELOG.md`:
+- Find the row where `Slug` = `{slug}`
+- Update `Status` → `Draft`
+- Update `Modules` → comma-separated list of modules from the spec's **Modules** header
+- If the row doesn't exist (spec written without going through forge-brainstorm), append it:
+  `| — | {slug} | {overview first sentence} | Draft | {modules} | — |`
+
+Then say:
 > "Spec written to `features/{slug}/spec.md`. Review it and say **yes** to generate the task breakdown."
 
 Do NOT add tasks to spec.md — tasks go in `features/{slug}/tasks.md` via `/forge-tasks`.

package/skills/forge-status/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: "forge-status"
+description: "Scans features/ and shows phase status for every feature: 🔵 brainstorming, 🟡 spec written, 🟠 tasks ready, ✅ contract complete. Suggests the next forge command for each in-progress feature."
+argument-hint: ""
+compatibility: "Requires spec repo with .forge/project.json"
+metadata:
+  author: "forge-workflow"
+  source: "spec-skills/forge-status/SKILL.md"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Forge Status
+
+Show the current status of all features in this spec repo, in changelog order.
+
+## Steps
+
+1. Read `features/CHANGELOG.md`.
+   - If missing or empty (no data rows): "No features yet. Run `/forge-brainstorm` to plan your first feature."
+   - Parse each row: `#`, `slug`, `description`, `status`, `modules`, `depends on`.
+
+2. For each row — in changelog order — determine its **live state** by checking the files
+   (overrides the stored status for in-progress detail):
+
+   | Files present | Live state |
+   |---|---|
+   | Nothing in `features/{slug}/` | 🔵 Brainstormed |
+   | `brainstorm.md` only | 🔵 Brainstormed |
+   | `spec.md` exists, no `tasks.md` | 🟡 Draft |
+   | `tasks.md` exists, no contract | 🟠 Open |
+   | Contract exists, unchecked tasks remain | 🟣 Implementing |
+   | All tasks checked (or `Status: Done` in tasks.md) | ✅ Done |
+
+3. For 🟣 Implementing features, read `tasks.md` and compute per-module completion
+   (ticked vs total under each `### {target}` heading).
+
+4. Flag any `Depends on` entries where the dependency is not yet ✅ Done — mark with ⚠️.
+
+## Output Format
+
+```
+Feature Status — {project}
+══════════════════════════════════════════════════════════════════
+ #   Slug                Status         Modules           Depends on
+──────────────────────────────────────────────────────────────────
+ 1   user-auth           ✅ Done         user-service       —
+ 2   payment-flow        🟣 Implementing  user-service 2/3   #1
+ 3   notification-prefs  🟠 Open          user-service       #1
+ 4   search-filters      🟡 Draft         user-service       —
+ 5   bulk-export         🔵 Brainstormed  —                  #3 ⚠️ not done yet
+══════════════════════════════════════════════════════════════════
+5 features  ·  1 done  ·  1 implementing  ·  3 in planning
+```
+
+The ⚠️ flag means "this feature's dependency is not yet Done — reconsider starting it."
+
+## What to Show Next
+After the table, suggest the next action for each non-done feature (in changelog order):
+- 🔵 Brainstormed → `/forge-spec {slug}`
+- 🟡 Draft → `/forge-tasks {slug}`
+- 🟠 Open → `/forge-contract {slug}`
+- 🟣 Implementing → "Module repos: `/forge-implement {slug}` → `/forge-done` → `/forge-close {slug} {module}`"

package/{forge-tasks → skills/forge-tasks}/SKILL.md

@@ -22,12 +22,20 @@ Generate the task breakdown for a feature and write it to a dedicated file.
   - If no → generate and write.
 
 ## Task breakdown rules
-- Group tasks by module using `### {module-name}` headings (use module names from `.forge/project.json`)
-- Each task gets a unique ID: `TASK-N` (sequential across all modules)
+
+Read `.forge/project.json` and build a flat list of **task targets** — the names used as `###` headings:
+- For a module with **no submodules** → the target is `{module.name}`
+- For a module **with submodules** → the targets are each `{submodule.name}` (the parent module name
+  is NOT used as a heading; submodules are treated exactly like standalone modules here)
+
+This means a submodule can later be promoted to its own repo with zero changes to `tasks.md`.
+
+- Group tasks by target using `### {target-name}` headings
+- Each task gets a unique ID: `TASK-N` (sequential across all targets)
 - Tag each task with type: `[api]` / `[feat]` / `[ui]` / `[test]` / `[infra]`
 - Write 1–3 acceptance criteria under each task
-- Order tasks within each module by dependency (what must be done first)
-- For frontend/consumer modules, reference the backend endpoint they integrate against
+- Order tasks within each target by dependency (what must be done first)
+- For frontend/consumer targets, reference the backend endpoint they integrate against
 
 ## Output file: `features/{slug}/tasks.md`
 
@@ -41,7 +49,7 @@ _(Status lifecycle: Open → Done, set by `/forge-close` when all modules finish
 
 ---
 
-### {module-name} ({type})
+### {target-name} ({type})
 
 - [ ] TASK-1 [api] {task title}
   - {acceptance criterion}
@@ -52,7 +60,7 @@ _(Status lifecycle: Open → Done, set by `/forge-close` when all modules finish
 
 ---
 
-### {module-name} ({type})
+### {target-name} ({type})
 
 - [ ] TASK-3 [ui] {task title}
   - {acceptance criterion}
@@ -67,10 +75,10 @@ Tasks: {feature-slug}
 - [ ] TASK-1 [api] POST /users/register
 - [ ] TASK-2 [feat] Password hashing
 
-### web-app (frontend)
+### admin (frontend)          ← submodule of webapps, but headed by its own name
 - [ ] TASK-3 [ui] Registration form component
 ══════════════════════════════════════════
-3 tasks across 2 modules
+3 tasks across 3 targets
 ```
 
 ## Gate

package/forge-status/SKILL.md

@@ -1,55 +0,0 @@
----
-name: "forge-status"
-description: "Scans features/ and shows phase status for every feature: 🔵 brainstorming, 🟡 spec written, 🟠 tasks ready, ✅ contract complete. Suggests the next forge command for each in-progress feature."
-argument-hint: ""
-compatibility: "Requires spec repo with .forge/project.json"
-metadata:
-  author: "forge-workflow"
-  source: "spec-skills/forge-status/SKILL.md"
-user-invocable: true
-disable-model-invocation: true
----
-
-# Forge Status
-
-Show the current status of all features in this spec repo.
-
-## Steps
-
-1. Scan the `features/` directory. If empty or missing, say "No features yet. Run `/forge-brainstorm` to plan your first feature."
-
-2. For each feature folder, determine its state (check in order, top to bottom):
-   - No `brainstorm.md` and no `spec.md` → 🔵 Brainstorming
-   - `brainstorm.md` exists, no `spec.md` → 🔵 Brainstormed
-   - `spec.md` exists, no `tasks.md` → 🟡 Spec written
-   - `tasks.md` exists, no contract file in `contracts/{any-module}/{slug}.yaml` → 🟠 Tasks ready
-   - Contract exists, but `tasks.md` has unchecked tasks → 🟣 Implementing
-   - Contract exists and all tasks in `tasks.md` are checked → ✅ Done
-
-3. For features in Implementing, read `tasks.md` and compute per-module completion
-   (ticked vs total under each `### {module}` heading) for the detail line.
-
-4. Also check `contracts/` for orphaned contracts (contract file exists but no matching feature folder) and flag them.
-
-## Output Format
-
-```
-Feature Status — {project} spec repo
-══════════════════════════════════════════════════════
-
-✅  user-auth           Done — all modules complete
-🟣  payment-flow        Implementing — user-service 2/3, web-app 0/2
-🟠  notification-prefs  Tasks ready — contract pending
-🟡  search-filters      Spec written — tasks pending
-🔵  bulk-export         Brainstormed — spec pending
-
-══════════════════════════════════════════════════════
-5 features  ·  1 done  ·  1 implementing  ·  3 planning
-```
-
-## What to Show Next
-After the table, suggest the next action for each non-done feature:
-- Brainstorming/Brainstormed → "Run `/forge-spec {slug}` to write the spec"
-- Spec written → "Run `/forge-tasks {slug}` to generate the task breakdown"
-- Tasks ready → "Run `/forge-contract {slug}` to generate the API contract"
-- Implementing → "Module repos run `/forge-implement {slug}`, then `/forge-done` → `/forge-close {slug} {module}`"