@khanhspring/forge-spec 1.0.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhspring/forge-spec",
-  "version": "1.0.1",
+  "version": "1.2.0",
   "description": "Forge spec repo skills for Claude Code — brainstorm, spec, tasks, contract, and more",
   "type": "module",
   "bin": {

package/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:
@@ -35,14 +61,15 @@ Before asking the user anything, research the existing codebase silently:
    Note any patterns, naming conventions, or prior decisions relevant to this idea.
 3. Scan `contracts/*/` — are there existing API contracts this feature will touch or extend?
    Note existing endpoint shapes, error formats, auth patterns.
-4. Read `CLAUDE.md` — note project principles, conventions, and forbidden patterns
-   that will constrain design choices.
+4. Read `CONTEXT.md` — note the actors, domain glossary, principles, conventions, and
+   forbidden patterns that will constrain design choices. Use glossary terms verbatim
+   in your questions and in the summary — never invent synonyms for existing domain terms.
 
 Report your findings before starting questions:
 
 > "Before we dive in, here's what I found in the codebase:
 > - [relevant existing feature or contract, or "No related features found"]
-> - [relevant principle from CLAUDE.md, or "No constraints found"]
+> - [relevant principle or constraint from CONTEXT.md, or "No constraints found"]
 >
 > I'll use this as context. Here's my understanding of the feature: {1–2 sentence restatement}
 > Is that right?"
@@ -57,7 +84,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).
@@ -183,7 +211,7 @@ apply the Research Handling pattern.
 ## Step 5 — Propose approaches
 
 Propose **2–3 design approaches** with trade-offs. Base them on the researched context
-from Step 1 — flag if an approach conflicts with existing patterns or CLAUDE.md principles.
+from Step 1 — flag if an approach conflicts with existing patterns or CONTEXT.md principles.
 
 ```
 I see 2–3 ways to approach this:
@@ -302,8 +330,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 +352,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/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/skills/forge-config/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: "forge-config"
-description: "View and interactively update .forge/project.json: add or remove modules, update ports, change stack info, or update the spec repo URL. Asks one question at a time and previews changes before writing."
-argument-hint: "Optional hint: 'add module', 'update user-service port', 'remove web-app'"
+description: "View and interactively update .forge/project.json (add/remove modules and submodules, ports, stack, spec repo URL) and CONTEXT.md (actors, glossary, principles, conventions). Asks one question at a time and previews changes before writing."
+argument-hint: "Optional hint: 'add module', 'add submodule to webapps', 'update user-service port', 'edit principles'"
 compatibility: "Requires spec repo with .forge/project.json"
 metadata:
   author: "forge-workflow"
@@ -12,14 +12,16 @@ disable-model-invocation: true
 
 # Forge Config
 
-View and update the project configuration at `.forge/project.json`.
+View and update the project configuration at `.forge/project.json`, and the
+project-wide domain context at `CONTEXT.md`.
 
 ## Step 1 — Load & display
 
 Read `.forge/project.json`.
 If missing: "No project config found. Run `/forge-init` to set up this repo first."
 
-Display the current config:
+Display the current config. Modules with submodules show one indented `↳` row per
+submodule — the parent row has no port/stack (those belong to each submodule):
 
 ```
 Project: {project-name}
@@ -28,13 +30,19 @@ Contract tool: {contract_tool}
 
 Modules ({n}):
   · user-service    backend   Spring Boot 3, Java 21   :8081
-  · web-app         frontend  React, TypeScript         :3000
+  · webapps         (3 submodules)
+    ↳ admin         frontend  React                    :3001   apps/admin
+    ↳ landing       frontend  Next.js                  :3000   apps/landing
+    ↳ portal        frontend  React                    :3002   apps/portal
 ```
 
 ## Step 2 — Determine the change
 
-From $ARGUMENTS, infer the intent if given (e.g. "add module", "update user-service port").
-If empty, ask: "What do you want to change? (add a module / remove a module / update a field / change spec repo URL)"
+From $ARGUMENTS, infer the intent if given (e.g. "add module", "add submodule to webapps",
+"update user-service port", "edit principles").
+If empty, ask: "What do you want to change? (add a module / add a submodule to an existing
+module / remove a module or submodule / update a field / change spec repo URL / edit project
+context — actors, glossary, principles, conventions)"
 
 ## Step 3 — Collect details (one question at a time)
 
@@ -44,22 +52,68 @@ Ask one question per message — never batch.
 1. "Module name? (kebab-case, must be unique)"
 2. "Type? (backend / frontend / worker / gateway)"
 3. "Tech stack? (e.g. 'Spring Boot 3, Java 21')"
-4. "Local dev port?"
-5. "Git repo URL? (or 'none')"
-6. "One-sentence description? (or 'none')"
-
-**Removing a module:**
-- Check whether any `features/*/tasks.md` has a `### {module}` section.
-  If so, warn: "`{module}` has tasks in {feature(s)}. Removing it from config won't delete those tasks. Remove anyway? (yes/no)"
-- Otherwise confirm: "Remove `{module}` from the project? (yes/no)"
+4. "Git repo URL? (or 'none')"
+5. "Does `{name}` contain multiple submodules — e.g. a monorepo with several apps,
+   or a Gradle multi-module build? (yes / no)"
+   - **If yes** → collect submodules one at a time (see below). Skip step 6 —
+     port and stack belong to each submodule, not the parent; drop the stack from step 3
+     if it was given for the parent.
+   - **If no** → continue.
+6. "Local dev port?" _(skip when the module has submodules)_
+7. "One-sentence description? (or 'none')"
+
+**Adding a submodule** (to an existing module) — ask which module first if not given.
+
+- If the parent is currently a **simple module** (no `submodules[]`), warn before converting:
+  > "`{module}` is currently a standalone module. Adding a submodule converts it:
+  > its `port` and `stack` move to the submodules — the parent keeps only `name`,
+  > `repo`, and `description`. If `{module}` already has tasks or contracts under its
+  > own name, those stay as-is and won't match a submodule name. Convert? (yes/no)"
+  If yes, ask whether the existing port/stack should become the first submodule
+  (asking for its `name` and `path`) or be discarded.
+- Then collect each new submodule, one field at a time (same as `/forge-init`):
+  1. "Submodule name? (kebab-case, unique across the whole project — not just within `{module}`)"
+  2. "Type? (backend / frontend / worker)"
+  3. "Stack?"
+  4. "Port?"
+  5. "Path within the `{module}` repo? (e.g. `apps/admin` or `auth-ui`)"
+  6. "One sentence: what does it do? _(Skip with 'none')_"
+- Confirm each: "`{sub}` — {type} — {stack} — :{port} — path: {path}. Another submodule? (yes / no)"
+
+> **Submodule rules (same as `/forge-init`):**
+> - No `repo` field on a submodule — it shares the parent module's repo
+> - No `port` or `stack` on a parent that has submodules
+> - Submodule names must be unique across the whole project — contracts live at
+>   `contracts/{submodule}/` and tasks.md uses `### {submodule}` headings directly
+
+**Removing a module or submodule:**
+- Check whether any `features/*/tasks.md` has a `### {name}` section (module name for
+  simple modules, submodule name for submodules).
+  If so, warn: "`{name}` has tasks in {feature(s)}. Removing it from config won't delete those tasks. Remove anyway? (yes/no)"
+- Otherwise confirm: "Remove `{name}` from the project? (yes/no)"
+- If removing the **last submodule** of a module, ask: "That's the last submodule of
+  `{module}`. Convert it back to a standalone module (needs a port and stack), or remove
+  the whole module?"
 
 **Updating a field:**
 - Show the current value, then ask for the new one:
   "`{module}.{field}` is currently `{old}`. What should it be?"
+- Submodule fields use the path `{module}.submodules[{sub}].{field}` — e.g.
+  "`webapps.submodules[admin].port` is currently `3001`. What should it be?"
+- Refuse to set `port` or `stack` on a parent with submodules, or `repo` on a
+  submodule — explain the rule instead.
 
 **Changing spec repo URL:**
 - "Current spec_repo is `{old}`. New URL?"
 
+**Editing project context (`CONTEXT.md`):**
+- Read `CONTEXT.md`. If missing, offer to create it with the template from `/forge-init`
+  Phase 6, asking the Phase 2 and Phase 4 questions to fill it.
+- Ask which section: "Which section? (What This Project Is / Business Goal / Actors /
+  Domain Glossary / Current State / Principles / Conventions / Out of Scope)"
+- Show the section's current content, then ask what to add, change, or remove.
+- Context edits go to `CONTEXT.md` only — never to CLAUDE.md or project.json.
+
 ## Step 4 — Preview & gate
 
 Show the before/after of exactly what will change:
@@ -69,19 +123,36 @@ Change preview:
   modules[user-service].port:  8081  →  8090
 ```
 
-> "Apply this change to `.forge/project.json`? Say **yes** to write, or tell me what to adjust."
+Adding a submodule:
+```
+Change preview:
+  modules[webapps].submodules  +  { name: reports, type: frontend,
+                                    stack: [React], port: 3003, path: apps/reports }
+```
+
+Converting a simple module to one with submodules, show the moved fields too:
+```
+Change preview:
+  modules[webapps].port   3000  →  (removed — moves to submodules)
+  modules[webapps].stack  [React]  →  (removed — moves to submodules)
+  modules[webapps].submodules  +  { name: admin, ... }
+```
+
+For CONTEXT.md edits, show the section before/after instead.
+
+> "Apply this change to `{file}`? Say **yes** to write, or tell me what to adjust."
 
 Wait for confirmation. Do not write before the user says yes.
 
 ## Step 5 — Write & confirm
 
-Apply the change, preserving all other fields and formatting.
-Confirm: "Updated `.forge/project.json` — {summary of what changed}."
+Apply the change, preserving all other fields, sections, and formatting.
+Confirm: "Updated `{file}` — {summary of what changed}."
 
-If a module name changed, warn:
-> "Heads up: `{module}` is referenced by the module repo's `.forge/module.json` and by
-> `### {module}` headings in tasks.md. Update those to match, or `/forge-implement` and
-> `/forge-close` will break."
+If a module or submodule name changed, warn:
+> "Heads up: `{name}` is referenced by the module repo's `.forge/module.json`, by
+> `### {name}` headings in tasks.md, and by the `contracts/{name}/` folder. Update
+> those to match, or `/forge-implement` and `/forge-close` will break."
 
 ## Schema Reference
 
@@ -90,6 +161,7 @@ If a module name changed, warn:
   "project": "my-project",        // short slug, no spaces
   "version": "1.0",
   "modules": [
+    // Module WITHOUT submodules — port and stack on the module itself:
     {
       "name": "user-service",     // kebab-case, matches module.json in module repos
       "repo": "git@github.com:org/user-service.git",
@@ -97,6 +169,23 @@ If a module name changed, warn:
       "stack": ["Spring Boot 3", "Java 21"],
       "port": 8081,
       "description": ""           // optional, one sentence
+    },
+    // Module WITH submodules — NO port/stack/type on the parent;
+    // each submodule owns type, stack, port, path; NO repo on submodules:
+    {
+      "name": "webapps",
+      "repo": "git@github.com:org/webapps.git",
+      "description": "Web app mono-repo",
+      "submodules": [
+        {
+          "name": "admin",        // kebab-case, unique across the WHOLE project
+          "type": "frontend",     // backend | frontend | worker
+          "stack": ["React"],
+          "port": 3001,
+          "path": "apps/admin",   // relative path inside the parent repo
+          "description": ""       // optional, one sentence
+        }
+      ]
     }
   ],
   "spec_repo": "git@github.com:org/specs.git",
@@ -108,6 +197,10 @@ If a module name changed, warn:
 ## Rules
 - One question per message — never batch
 - Never write before the user confirms the preview in Step 4
-- `module.name` must be kebab-case and unique
-- `module.name` must match the `module` field in the module repo's `.forge/module.json`
-- Never silently remove a module that has tasks referencing it — warn first
+- `module.name` must be kebab-case and unique; submodule names must be unique across
+  the whole project (contracts and task headings use the submodule name directly)
+- `module.name` must match the `module` field in the module repo's `.forge/module.json`;
+  submodule names must match the `submodules[].name` entries there
+- A module has EITHER `port`+`stack` OR `submodules[]` — never both; submodules never
+  have a `repo` field
+- Never silently remove a module or submodule that has tasks referencing it — warn first

package/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/skills/forge-init/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: "forge-init"
-description: "One-time initialization for a Forge spec repo. Walks through setup conversationally one question at a time, then writes .forge/project.json, CLAUDE.md, and directory scaffolding on confirmation."
+description: "One-time initialization for a Forge spec repo. Walks through setup conversationally one question at a time — project identity, project details, modules, principles — then writes .forge/project.json, CONTEXT.md, CLAUDE.md, and directory scaffolding on confirmation."
 argument-hint: "Optional: project name to skip the first prompt"
 compatibility: "Run once in a spec repo before any other forge skills. Safe to re-run — never overwrites existing files."
 when_to_use: >
@@ -40,7 +40,40 @@ _(Skip with 'none' if it's not set up yet — you can add it later with `/forge-
 
 ---
 
-## Phase 2 — Modules
+## Phase 2 — Project details
+
+These answers become `CONTEXT.md` — the project-wide domain context that
+`/forge-brainstorm` and `/forge-spec` read before planning, and that module repos
+see at `specs/CONTEXT.md` during implementation. Getting this right once saves
+re-explaining the project in every feature conversation.
+
+Start by offering the shortcut:
+> "If you have a project overview doc (README, pitch doc, Confluence page), paste it
+> and I'll extract these answers — otherwise I'll ask a few short questions."
+
+If a doc is pasted, extract what's covered and ask only about genuine gaps.
+Otherwise ask one question at a time:
+
+**Q1.** "Who uses this system? List the actors/roles and what each one does.
+_(e.g. 'customer — places orders; admin — manages the catalog; billing-worker — system actor')_"
+
+**Q2.** "What are the core domain concepts, in your team's own words?
+_(e.g. 'Order, Quote, Fulfillment — a Quote becomes an Order when accepted')_
+These become the domain glossary — the exact terms specs and contracts will use."
+
+**Q3.** "What's the business goal — what does success look like for this project?
+_(1–2 sentences, or 'skip')_"
+
+**Q4.** "What's the current state? Greenfield, or are there existing systems this
+replaces or integrates with?
+_(e.g. 'replacing a legacy PHP monolith; auth stays in Keycloak')_"
+
+Keep this phase capped at these four areas — deep per-feature questioning is
+`/forge-brainstorm`'s job, not init's.
+
+---
+
+## Phase 3 — Modules
 
 Collect modules one at a time. Each module is gathered field by field.
 
@@ -53,16 +86,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?"
 
@@ -70,11 +126,11 @@ Then ask:
 > "Any more modules to add? (yes / no)"
 
 If yes, repeat from step 1 of this phase for the next module.
-If no, move to Phase 3.
+If no, move to Phase 4.
 
 ---
 
-## Phase 3 — Principles & conventions
+## Phase 4 — Principles & conventions
 
 Ask one at a time. "None" or "not yet" are valid answers — these sections can be filled
 in later with `/forge-config`.
@@ -93,7 +149,7 @@ Say 'none yet' to skip._"
 
 ---
 
-## Phase 4 — Preview & gate
+## Phase 5 — Preview & gate
 
 Show a full preview of what will be written:
 
@@ -105,14 +161,21 @@ Ready to initialize. Here's what I'll create:
   modules: {n} module(s): {comma-separated names}
   spec_repo: {url or "not set"}
 
-CLAUDE.md
+CONTEXT.md
   Description: {description}
-  Modules: {n} listed
+  Actors: {n} listed
+  Domain glossary: {n} terms
+  Business goal: {one line or "skipped"}
+  Current state: {one line}
   Principles: {list or "none yet"}
   Conventions: {list or "none yet"}
   Out of scope: {list or "none yet"}
 
-features/.gitkeep
+CLAUDE.md
+  Modules: {n} listed
+  Forge workflow + structure + pointer to CONTEXT.md
+
+features/CHANGELOG.md
 contracts/.gitkeep
 .gitignore  ← append Forge entries
 ```
@@ -123,9 +186,11 @@ Wait for confirmation. Do not write anything before the user says yes.
 
 ---
 
-## Phase 5 — Write files
+## Phase 6 — Write files
 
 Write `.forge/project.json`:
+
+Module **without** submodules — `port` and `stack` on the module itself:
 ```json
 {
   "project": "{project-name}",
@@ -146,17 +211,98 @@ Write `.forge/project.json`:
 }
 ```
 
-Write `CLAUDE.md`:
+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 `CONTEXT.md` — the single source of truth for project-wide domain context.
+Fill every section from the Phase 1, 2, and 4 answers; write "None defined yet." only
+where the user explicitly skipped:
+```markdown
+# {project-name} — Project Context
+
+> Domain context for all planning and implementation. `/forge-brainstorm` and
+> `/forge-spec` read this before any feature work; module repos see it at
+> `specs/CONTEXT.md`. Keep it current via `/forge-config`.
+
+## What This Project Is
+{description — 2–4 sentences built from the user's answers, not just the one-liner}
+
+## Business Goal
+{goal — or "Not defined yet."}
+
+## Actors
+| Actor | Who they are | What they do in the system |
+|-------|--------------|----------------------------|
+| {role} | {description} | {responsibilities} |
+
+## Domain Glossary
+| Term | Meaning |
+|------|---------|
+| {term} | {definition in the team's own words} |
+
+## Current State
+{greenfield / existing systems, integrations, migration notes}
+
+## Principles
+{list each as a bullet — or "None defined yet."}
+
+## Conventions
+{list each as a bullet — or "None defined yet."}
+
+## Out of Scope / Forbidden
+{list each as a bullet — or "None defined yet."}
+```
+
+Write `CLAUDE.md` — operational only; domain context lives in `CONTEXT.md`, never
+duplicate it here:
 ```markdown
 # {project-name}
 
-{description}
+{description — the 1–2 sentence version}
+
+## Project Context
+Actors, domain glossary, principles, and conventions live in `CONTEXT.md`.
+Read it before any brainstorm, spec, or planning work.
 
 ## Modules
 | Name | Type | Stack | Port |
 |------|------|-------|------|
 | {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
@@ -164,26 +310,28 @@ Write `CLAUDE.md`:
 4. `/forge-contract`   — generate Specmatic OpenAPI contracts
 5. `/forge-close {slug} {module}` — mark a module's tasks done (after module repo ships)
 
-Utilities: `/forge-status` (feature dashboard) · `/forge-config` (edit modules/ports)
-
-## Principles
-{list each as a bullet — or "None defined yet."}
-
-## Conventions
-{list each as a bullet — or "None defined yet."}
-
-## Out of Scope / Forbidden
-{list each as a bullet — or "None defined yet."}
+Utilities: `/forge-status` (feature dashboard) · `/forge-config` (edit modules/ports/context)
 
 ## Structure
+- `CONTEXT.md`                    — project-wide domain context (actors, glossary, principles)
 - `features/{slug}/brainstorm.md` — approved brainstorm summary
 - `features/{slug}/spec.md`       — requirements, flows, API list
 - `features/{slug}/tasks.md`      — per-module task breakdown with checkboxes
 - `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:
@@ -199,7 +347,14 @@ Run `git status` and confirm:
 
 ## Rules
 - One question per message — never ask multiple questions at once
-- Never write files before the user says yes in Phase 4
+- Never write files before the user says yes in Phase 5
+- Each fact lives in exactly one file: domain context in `CONTEXT.md`, machine config
+  in `.forge/project.json`, workflow instructions in `CLAUDE.md` — never duplicate
+  content across them
 - 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/skills/forge-spec/SKILL.md

@@ -44,9 +44,10 @@ Before asking anything, research silently:
    - How Non-Functional requirements are typically written
    - Any related feature whose requirements this feature extends or depends on
 
-2. **CLAUDE.md** — note project principles and conventions.
+2. **CONTEXT.md** — note the actors, domain glossary, principles, and conventions.
    Any principle that implies a requirement for this feature?
    (e.g. "API contract before implementation" → this feature needs a contract requirement)
+   Use glossary terms verbatim in requirements — never invent synonyms for existing domain terms.
 
 3. **Brainstorm open items** — extract from the brainstorm summary:
    - Any item listed under **Open Questions** that wasn't resolved
@@ -58,7 +59,7 @@ Report findings:
 > "Before drafting, here's what I found:
 > - Related features: {list or 'none'}
 > - Unresolved from brainstorm: {open questions / assumptions — or 'none, all clear'}
-> - CLAUDE.md principles that apply: {list or 'none'}
+> - CONTEXT.md principles that apply: {list or 'none'}
 > - Naming convention: {e.g. 'REQ-N restarts per feature'}"
 
 ---
@@ -270,9 +271,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

@@ -12,44 +12,52 @@ disable-model-invocation: true
 
 # Forge Status
 
-Show the current status of all features in this spec repo.
+Show the current status of all features in this spec repo, in changelog order.
 
 ## Steps
 
-1. Scan the `features/` directory. If empty or missing, say "No features yet. Run `/forge-brainstorm` to plan your first feature."
+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 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
+2. For each row — in changelog order — determine its **live state** by checking the files
+   (overrides the stored status for in-progress detail):
 
-3. For features in Implementing, read `tasks.md` and compute per-module completion
-   (ticked vs total under each `### {module}` heading) for the detail line.
+   | 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 |
 
-4. Also check `contracts/` for orphaned contracts (contract file exists but no matching feature folder) and flag them.
+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} 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
+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:
-- 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}`"
+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/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