@khanhspring/forge-module 1.2.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhspring/forge-module",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Forge module repo skills for Claude Code — implement, contract-test, done, and more",
   "type": "module",
   "bin": {

package/skills/forge-contract-test/SKILL.md

@@ -15,11 +15,17 @@ disable-model-invocation: true
 Run or analyze Specmatic contract tests for this module.
 
 ## Pre-check
-- Read `.forge/module.json`.
+- Read `.forge/module.json` for `module` and `spec_submodule_path`.
   If missing, say "Run forge-init to set up this module repo first."
+- Read `{spec_submodule_path}/.forge/project.json` and find the `modules[]` entry where
+  `name == module` — port and submodule structure live there, not in module.json.
 - Determine scope:
-  - Has no `submodules` key → single module; use top-level `contract_glob` and `test_base_url`.
-  - Has `submodules[]` → module with submodules; show one command block per submodule.
+  - Entry has no `submodules[]` → single module; derive `contract_glob =
+    {spec_submodule_path}/contracts/{module}/*.yaml` and `test_base_url =
+    http://localhost:{entry.port}`.
+  - Entry has `submodules[]` → module with submodules; show one command block per submodule,
+    deriving each one's `contract_glob = {spec_submodule_path}/contracts/{submodule.name}/*.yaml`
+    and `test_base_url = http://localhost:{submodule.port}`.
 
 ## If $ARGUMENTS is empty — Output the test command(s)
 

package/skills/forge-done/SKILL.md

@@ -2,7 +2,7 @@
 name: "forge-done"
 description: "Confirms all tasks for this module are complete and generates the module repo commit message. Module repo only — run /forge-close in the spec repo afterward to mark tasks done there."
 argument-hint: "Feature slug (e.g. 'user-registration')"
-compatibility: "Requires module repo with .forge/module.json and an initialized specs/ git submodule"
+compatibility: "Requires module repo with .forge/module.json and an initialized specs/ link (git submodule or junction)"
 metadata:
   author: "forge-workflow"
   source: "module-skills/forge-done/SKILL.md"
@@ -28,20 +28,22 @@ is handled separately by `/forge-close` in the spec repo.
 
 ---
 
-## Step 1 — Read task list (read-only from submodule)
+## Step 1 — Read task list (read-only from specs/)
 
 Read `{spec_submodule_path}/features/{slug}/tasks.md`.
 
-- If `module.json` has no `submodules` key: find the `### {module}` section.
-- If `module.json` has `submodules[]`: find the `### {submodule.name}` section for each entry;
-  show them grouped by submodule name in Step 2.
+Read `{spec_submodule_path}/.forge/project.json` and find the `modules[]` entry where
+`name == module` — submodule structure lives there, not in module.json:
+- Entry has no `submodules[]`: find the `### {module}` section.
+- Entry has `submodules[]`: find the `### {submodule.name}` section for each entry; show them
+  grouped by submodule name in Step 2.
 
 If `tasks.md` is missing:
 > "No tasks file found at `specs/features/{slug}/tasks.md`.
 > Run `/forge-tasks {slug}` in the spec repo first."
 
-Note: the submodule is read-only — task checkboxes cannot be updated from here.
-That is handled by `/forge-close` in the spec repo.
+Note: `specs/` is read-only from here regardless of link type — task checkboxes cannot be
+updated from this repo. That is handled by `/forge-close` in the spec repo.
 
 ---
 

package/skills/forge-implement/SKILL.md

@@ -2,7 +2,7 @@
 name: "forge-implement"
 description: "Researches existing codebase patterns, clears ambiguities one at a time, challenges implementation concerns, then guides task-by-task implementation scoped to this module. No code written until plan is confirmed."
 argument-hint: "Feature slug (e.g. 'user-registration')"
-compatibility: "Requires module repo with .forge/module.json and an initialized specs/ git submodule"
+compatibility: "Requires module repo with .forge/module.json and an initialized specs/ link (git submodule or junction)"
 metadata:
   author: "forge-workflow"
   source: "module-skills/forge-implement/SKILL.md"
@@ -25,17 +25,24 @@ presented the Implementation Plan and the user has explicitly confirmed it.
 ## Pre-check
 
 - Read `.forge/module.json` — if missing, say "Run `/forge-init` to set up this module repo first."
-- Get `spec_submodule_path` from module.json.
-- **Determine working scope:**
-  - `module.json` has no `submodules` → scope = the module itself; use top-level `test_base_url` and `contract_glob`.
-  - `module.json` has `submodules[]` → ask "Which submodule are you implementing? ({list submodule names})"
-    then use that submodule's `path`, `test_base_url`, and `contract_glob`.
+- Get `module`, `spec_submodule_path`, and `spec_link_type` from module.json.
+- **Determine working scope** from the spec repo, not module.json:
+  - Read `{spec_submodule_path}/.forge/project.json` and find the `modules[]` entry where
+    `name == module`. If not found, warn: "`{module}` isn't registered in the spec repo's
+    `project.json` — check the name matches, or add it there via `/forge-config`."
+  - Entry has no `submodules[]` → scope = the module itself; `test_base_url =
+    http://localhost:{entry.port}`, `contract_glob = {spec_submodule_path}/contracts/{module}/*.yaml`.
+  - Entry has `submodules[]` → ask "Which submodule are you implementing? ({list submodule names
+    from the entry})", then use that submodule's `path`, and derive `test_base_url =
+    http://localhost:{submodule.port}`, `contract_glob =
+    {spec_submodule_path}/contracts/{submodule.name}/*.yaml`.
 - Feature slug from $ARGUMENTS.
   - If empty, scan `{spec_submodule_path}/features/*/tasks.md` for `### {scope-name}` headings
     (module name for simple modules, submodule name for submodules), list features with pending
     tasks, ask which to implement.
-- Check `git submodule status` — if specs/ is out of date, say:
+- If `spec_link_type` is `"submodule"` (or unset), check `git submodule status` — if specs/ is out of date, say:
   > "Your specs submodule may be out of date. Run `git submodule update --remote specs` first, or continue with the current version?"
+- If `spec_link_type` is `"junction"`, skip this check — a junction/symlink always reflects the live spec folder.
 
 ---
 

package/skills/forge-init/SKILL.md

@@ -34,7 +34,9 @@ Before asking anything, silently scan the repo and note:
 
 1. **Stack detection** — does `pom.xml`, `build.gradle`, `package.json`, `go.mod`, `requirements.txt`, or similar exist? What versions are declared?
 2. **Port detection** — is a port configured in `application.yml`, `application.properties`, `.env`, `.env.example`, or `docker-compose.yml`?
-3. **Specs submodule** — does `specs/` already exist as a directory or submodule?
+3. **Specs link** — does `specs/` already exist? If so, determine how: a git submodule
+   (check `.gitmodules` / `git submodule status`) or a junction/symlink (check if it's a
+   reparse point / symlink, e.g. `git submodule status` reports nothing but the dir exists).
 4. **CI** — does `.github/workflows/` already exist? Any contract test workflow present?
 5. **Existing CLAUDE.md** — already has project context written?
 6. **Monorepo signals** — does `nx.json`, `turbo.json`, `lerna.json`, `pnpm-workspace.yaml`, or
@@ -47,39 +49,20 @@ Report findings before asking anything:
 > "Here's what I found in this repo:
 > - Stack: {detected stack — or 'not detected'}
 > - Port: {detected port — or 'not found in config'}
-> - specs/ submodule: {exists / not present}
+> - specs/: {not present / exists — git submodule / exists — junction or symlink}
 > - GitHub Actions: {exists / not present}
 > {if monorepo signals}: - Looks like a monorepo — detected sub-apps: {list of dir names}
 >
 > I'll use these as defaults — just confirm or correct as we go."
 
-**If monorepo/multi-module signals were found**, ask immediately after the report:
-> "This looks like a module with submodules ({names}).
-> Should I configure them as submodules so each gets its own tasks and contracts? (yes / no)"
+**If monorepo/multi-module signals were found**, note it in passing — no question needed:
+> "This looks like a module with submodules ({names}). Submodule structure (ports, stack,
+> paths) lives in the spec repo's `project.json`, not here — I'll cross-check against that
+> once `specs/` is linked."
 
-If yes → collect submodule details in Step 2-B before the main questions.
-If no → proceed as a single module.
-
----
-
-## Step 2-B — Submodule collection (only when confirmed)
-
-Submodules share the parent module's repo — they are not separate repos.
-Collect them one at a time. Pre-fill from what was detected and ask the user to confirm or correct:
-
-- "Submodule name? _(Must match a `name` under this module's `submodules` in the spec repo's `project.json`; default: `{detected-dir-name}`)_"
-- "Type? (backend / frontend / worker)"
-- "Stack? (detected: {stack-if-found} — or enter manually)"
-- "Port? _(each submodule has its own port — detected: {port-if-found})_"
-- "Path within this repo? (default: `{detected-path}`)"
-
-Confirm: "`{sub}` — {type} — {stack} — :{port} — {path}. Another submodule? (yes / no)"
-
-**Rules enforced here:**
-- Submodules have no `repo` field — they are in the same repo as the parent module
-- Port is collected per submodule; the parent module has no `port`
-
-After collecting all submodules, continue to Step 2 (Q4 port will be skipped automatically).
+Submodule structure is never collected or stored in this repo's `.forge/module.json`. It's
+configured once in the spec repo via `/forge-config` there, and every module skill reads it
+from `specs/.forge/project.json` at runtime. This repo only needs to know its own module name.
 
 ---
 
@@ -89,57 +72,70 @@ Ask one question per message. Wait for the answer before asking the next.
 Where research already gives a confident answer, present it as a default to confirm
 rather than asking from scratch.
 
-**Q1 — Module name** _(skip if Step 2-B was run)_
+**Q1 — Module name**
 > "What's the module name for this repo?
 > _(Must exactly match a `name` entry in the spec repo's `.forge/project.json`)_"
 
 Do not suggest a default — module names must be exact matches. Warn clearly:
 > "This name must match exactly. A mismatch will break `/forge-implement` and `/forge-done`."
 
+If `specs/` was already detected in Step 1 (already linked), read
+`{specs-path}/.forge/project.json` now and find the `modules[]` entry where `name` matches
+this answer. If found, silently keep its `port`, `stack`, `type`, and `submodules[]` (if any)
+for use in the Step 3 preview and the CLAUDE.md content written in Step 4 — do not re-ask for
+any of it. If not found, note it and continue: "Heads up — `{module}` isn't in the spec repo's
+`project.json` yet. Add it there with `/forge-config`, or continue and I'll leave stack/port
+as TBD in CLAUDE.md for now." If `specs/` isn't linked yet, this lookup happens later, in
+Step 4, right after the link is created.
+
 **Q2 — Module description**
 > "What does this module do? (one sentence)"
 
-**Q3 — Spec repo URL**
-
-If `specs/` already exists:
-> "I see a `specs/` directory already — is that the spec repo submodule? (yes/no)
-> If yes, what's the remote URL? (run `git remote -v` in `specs/` if unsure)"
-
-If not:
-> "What's the spec repo URL? (it will be added as a git submodule at `specs/`)"
-
-**Q4 — Port** _(skip entirely if Step 2-B was run — port belongs to each submodule, not the module)_
-
-If port was detected in Step 1:
-> "I found port `{port}` in your config — is that the right local dev port? (yes / enter different port)"
-
-If not detected:
-> "What port does this module run on locally?"
-
-**Q5 — Tech stack**
-
-If stack was detected in Step 1:
-> "Looks like this is a `{detected stack}` module — is that right? Anything to add?"
-
-If not detected:
-> "What's the tech stack? (e.g. 'Spring Boot 3, Java 21' or 'React, TypeScript')"
-
-**Q6 — Principles**
+**Q3 — Spec repo link**
+
+If `specs/` already exists, confirm what was detected in Step 1 instead of asking from scratch:
+- Detected as a git submodule → "I see `specs/` is already a git submodule — is that the spec
+  repo? (yes/no). If yes, what's the remote URL? (run `git remote -v` in `specs/` if unsure)"
+- Detected as a junction/symlink → "I see `specs/` is already a local junction/symlink — what
+  local path does it point at? (confirm or correct)"
+- Set `spec_link_type` accordingly and skip straight to Q4.
+
+If `specs/` does not exist, ask how to link it:
+> "How should this repo link to the spec repo?
+> 1. **Git submodule** (default) — versioned and works across machines/CI, but needs
+>    `git submodule update --remote specs` to sync after spec repo changes.
+> 2. **Junction / local link** — for when the spec repo and this module repo live on the same
+>    machine (solo/local dev). `specs/` always reflects the live folder, no sync command needed —
+>    but it won't survive being cloned elsewhere or used in CI, and skips version pinning."
+
+- **If git submodule (or no answer / "default")**:
+  > "What's the spec repo URL? (it will be added as a git submodule at `specs/`)"
+  Set `spec_link_type: "submodule"`.
+- **If junction/local link**:
+  > "What's the local path to the spec repo folder? (absolute path, e.g. `D:\Workspace\my-specs`
+  > or `/home/me/my-specs`)"
+  Set `spec_link_type: "junction"` and `spec_source_path` to the given absolute path.
+
+Note: port, stack, and submodule structure are never asked here — they come from the spec
+repo's `project.json` (looked up in Q1 if `specs/` already existed, or in Step 4 right after
+linking otherwise). `.forge/module.json` doesn't store any of it either way.
+
+**Q4 — Principles**
 > "What are the key architectural principles for this module?
 > _(e.g. 'stateless', 'no business logic in controllers', 'repository pattern for DB access')
 > Say 'none yet' to skip._"
 
-**Q7 — Conventions**
+**Q5 — Conventions**
 > "Any coding conventions the team follows in this repo?
 > _(e.g. 'constructor injection only', 'all public methods must have unit tests', 'no magic strings')
 > Say 'none yet' to skip._"
 
-**Q8 — Never**
+**Q6 — Never**
 > "Anything developers should never do in this codebase?
 > _(e.g. 'no direct DB calls from the API layer', 'never change a contract to fix a failing test')
 > Say 'none yet' to skip._"
 
-**Q9 — GitHub Actions CI**
+**Q7 — GitHub Actions CI**
 
 If `.github/workflows/` already exists with a contract test:
 > "I see a CI workflow already exists — skip adding another? (yes to skip)"
@@ -157,24 +153,25 @@ Show a full preview of everything that will be created or run:
 ```
 Ready to initialize. Here's what I'll do:
 
-{if specs/ not present}
+{if specs/ not present, spec_link_type = submodule}
   git submodule add {spec-repo-url} specs
   git submodule update --init --recursive
 
+{if specs/ not present, spec_link_type = junction}
+  {Windows}  mklink /J specs "{spec-source-path}"
+  {macOS/Linux}  ln -s "{spec-source-path}" specs
+  append `specs/` to .gitignore  (junction contents aren't tracked by this repo)
+
 .forge/module.json
-  {if single app}
-  module:        {module-name}
-  test_base_url: http://localhost:{port}
-  contract_glob: specs/contracts/{module-name}/*.yaml
-  {if submodules}
-  submodules:
-    {sub-name}  path:{path}  :{port}  contract: specs/contracts/{sub-name}/*.yaml
-    ...
+  module:              {module-name}
+  spec_submodule_path: specs
+  spec_link_type:      {submodule | junction}
+  {if junction} spec_source_path: {spec-source-path}
 
 CLAUDE.md
   Module:       {module-name}
   Description:  {description}
-  Stack:        {stack}  Port: {port}
+  Stack/Port:   {from spec repo's project.json, or "TBD — set via /forge-config in the spec repo"}
   Principles:   {list or "none yet"}
   Conventions:  {list or "none yet"}
   Never:        {list or "none yet"}
@@ -192,50 +189,51 @@ Wait for confirmation. Do not write files or run git commands before the user sa
 
 ## Step 4 — Write files
 
-Run (if specs/ not already present):
+Run (if specs/ not already present), based on the chosen `spec_link_type`:
+
+**`submodule`:**
 ```bash
 git submodule add {spec-repo-url} specs
 git submodule update --init --recursive
 ```
 
-Write `.forge/module.json`:
-
-**For a single-app module** (no sub-apps):
-```json
-{
-  "module": "{module-name}",
-  "spec_submodule_path": "specs",
-  "specmatic_version": "2.x",
-  "test_base_url": "http://localhost:{port}",
-  "contract_glob": "specs/contracts/{module-name}/*.yaml"
-}
+**`junction`:**
+```bash
+# Windows
+mklink /J specs "{spec-source-path}"
+# macOS/Linux
+ln -s "{spec-source-path}" specs
 ```
+Then append `specs/` to `.gitignore` — a junction/symlink's contents belong to the spec repo,
+not this one, and must not be tracked or committed here.
 
-**Module with submodules** — no top-level `port` or `test_base_url`; each submodule owns those.
-Submodules have no `repo` field — they are in the same repo as the parent module:
+If the Q1 lookup didn't already happen (i.e. `specs/` was just created above, not already
+present in Step 1), read `{spec_submodule_path}/.forge/project.json` now and find the
+`modules[]` entry where `name` matches the module name from Q1. Use its `port`, `stack`, and
+`submodules[]` (if any) to fill the CLAUDE.md content below. If the module still isn't found
+there, write "TBD — set via `/forge-config` in the spec repo" for the stack/port line instead.
+
+Write `.forge/module.json` — same shape whether or not the module has submodules in the spec
+repo, since submodule structure is never duplicated here:
 ```json
 {
   "module": "{module-name}",
   "spec_submodule_path": "specs",
-  "specmatic_version": "2.x",
-  "submodules": [
-    {
-      "name": "{sub-name}",
-      "path": "{relative-path}",
-      "test_base_url": "http://localhost:{port}",
-      "contract_glob": "specs/contracts/{sub-name}/*.yaml"
-    }
-  ]
+  "spec_link_type": "submodule"
 }
 ```
+`spec_link_type` is `"submodule"` (default) or `"junction"`. When `"junction"`, also write
+`"spec_source_path": "{absolute-local-path}"` so the link can be recreated if it's ever lost.
 
-Write `CLAUDE.md`:
+Write `CLAUDE.md`. `{stack}`/`{port}`/`{path}` below come from the spec repo's `project.json`
+lookup above (or "TBD" if not found there yet) — never from a question asked in this skill:
 ```markdown
 # {module-name}
 
 {description}
 
-_(Single app: show Stack + Port inline. Monorepo: replace with a table.)_
+_(Single app: show Stack + Port inline. Monorepo: replace with a table, one row per submodule
+found in the spec repo's project.json.)_
 
 **Stack:** {stack}  **Port:** {port}
 
@@ -253,9 +251,15 @@ _(Single app: show Stack + Port inline. Monorepo: replace with a table.)_
 5. (then in the spec repo) `/forge-close {slug} {module}` — mark tasks done there
 
 ## Spec repo
-Linked via git submodule at `specs/`.
+_(submodule)_ Linked via git submodule at `specs/`.
 Run `git submodule update --remote specs` before starting a new feature,
 and again after `/forge-close` is run in the spec repo to sync task status.
+
+_(junction)_ Linked via local junction/symlink at `specs/` → `{spec-source-path}`.
+Always reflects the live spec repo folder — no sync command needed. This only works while
+both repos are on the same machine; switch to a git submodule (`/forge-init` again, or
+re-run link setup) before cloning this repo elsewhere or using it in CI.
+
 Project-wide domain context (actors, glossary, principles) lives at `specs/CONTEXT.md`
 — read it before implementing.
 
@@ -304,6 +308,9 @@ Run `git status` and confirm:
 - Never overwrite existing files
 - All written files must be complete — no unfilled placeholders
 - `module` in module.json must exactly match the name in the spec repo's project.json
+- `module.json` never stores `port`, `stack`, or submodule structure — those live only in the
+  spec repo's `project.json`; every module skill resolves them at runtime by reading
+  `specs/.forge/project.json`
 - **Extract, don't re-ask**: if the user's answer contains information for upcoming fields
   (e.g. "it's a NestJS app on port 3000 at apps/auth-ui"), extract and fill those fields
   silently — only ask about what is genuinely missing. Never ask a question the user has

package/skills/forge-tasks/SKILL.md

@@ -2,7 +2,7 @@
 name: "forge-tasks"
 description: "Lists all tasks assigned to this module across every feature, with completion status, by scanning the spec submodule. Module repo task dashboard."
 argument-hint: ""
-compatibility: "Requires module repo with .forge/module.json and an initialized specs/ git submodule"
+compatibility: "Requires module repo with .forge/module.json and an initialized specs/ link (git submodule or junction)"
 metadata:
   author: "forge-workflow"
   source: "module-skills/forge-tasks/SKILL.md"
@@ -15,16 +15,23 @@ disable-model-invocation: true
 Show all tasks assigned to this module across all features.
 
 ## Pre-check
-- Read `.forge/module.json` for `module` and `spec_submodule_path`.
+- Read `.forge/module.json` for `module`, `spec_submodule_path`, and `spec_link_type`.
   If missing: "Run `/forge-init` to set up this module repo first."
-- If `specs/` is not initialized: suggest `git submodule update --init --recursive`
-- Optionally suggest `git submodule update --remote specs` to get the latest task status.
+- If `spec_link_type` is `"submodule"` (or unset, for repos initialized before this field existed):
+  - If `specs/` is not initialized: suggest `git submodule update --init --recursive`
+  - Optionally suggest `git submodule update --remote specs` to get the latest task status.
+- If `spec_link_type` is `"junction"`:
+  - If `specs/` is missing or broken, suggest recreating the link at `spec_source_path`
+    (Windows: `mklink /J specs "{spec_source_path}"`; macOS/Linux: `ln -s "{spec_source_path}" specs`).
+  - No sync command needed — a junction/symlink always reflects the live folder.
 
 ## Steps
 
-Determine the set of task headings to look for:
-- `module.json` has no `submodules` → look for `### {module}` (one heading).
-- `module.json` has `submodules[]` → look for `### {submodule.name}` for each entry.
+Determine the set of task headings to look for. Read `{spec_submodule_path}/.forge/project.json`
+and find the `modules[]` entry where `name == module` (from module.json) — submodule structure
+is never stored in module.json itself:
+- Entry has no `submodules[]` → look for `### {module}` (one heading).
+- Entry has `submodules[]` → look for `### {submodule.name}` for each entry.
   Submodule task headings use the submodule's own name — no parent prefix — so they are
   identical to standalone module headings and can be promoted without touching tasks.md.
 
@@ -65,7 +72,8 @@ Feature: user-registration  [Open]
 ```
 
 If no tasks reference this module across any feature:
-> "No tasks found for `{module}`. Either no feature targets this module yet, or the specs
-> submodule is out of date — try `git submodule update --remote specs`."
+> "No tasks found for `{module}`. Either no feature targets this module yet, {if submodule}
+> or the specs submodule is out of date — try `git submodule update --remote specs`.
+> {if junction} or the linked spec folder doesn't have it yet."
 
 After showing: "Tell me which feature to implement, or run `/forge-implement {slug}`."