diff --git a/.cursor/rules/audit-code.mdc b/.cursor/rules/audit-code.mdc index e99672d0..06b2f4cc 100644 --- a/.cursor/rules/audit-code.mdc +++ b/.cursor/rules/audit-code.mdc @@ -26,7 +26,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. -- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code diff --git a/.cursor/rules/craft-skill.mdc b/.cursor/rules/craft-skill.mdc index 8a667ac3..d7b784f4 100644 --- a/.cursor/rules/craft-skill.mdc +++ b/.cursor/rules/craft-skill.mdc @@ -29,7 +29,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr - Any reference materials to include? - What specs/ output does it produce (if any)? -2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md): +2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md): - Is it atomic (verb-noun)? - Is it "deep" (simple interface, complex internal logic)? - Does it include Hard Gates? @@ -42,7 +42,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source. -4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md). +4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md). > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent. diff --git a/.cursor/rules/elaborate-spec.mdc b/.cursor/rules/elaborate-spec.mdc index 6eba98b6..e06eeb8e 100644 --- a/.cursor/rules/elaborate-spec.mdc +++ b/.cursor/rules/elaborate-spec.mdc @@ -62,7 +62,7 @@ Once the user has answered the main questions, probe for assumptions: ### 4. Synthesize and confirm -Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md): +Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md): - The problem (feeds into §1 Business narrative) - The solution and main flow (feeds into §5) - The key constraints and alternative flows (feeds into §6) diff --git a/.cursor/rules/evolve-skill.mdc b/.cursor/rules/evolve-skill.mdc index 702408b8..b9068512 100644 --- a/.cursor/rules/evolve-skill.mdc +++ b/.cursor/rules/evolve-skill.mdc @@ -51,4 +51,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template. **Evidence:** path/to/benchmark-report.md ``` -Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/` +Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path. diff --git a/.cursor/rules/grill-me.mdc b/.cursor/rules/grill-me.mdc index 28c78e7b..0776a792 100644 --- a/.cursor/rules/grill-me.mdc +++ b/.cursor/rules/grill-me.mdc @@ -75,7 +75,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio When an assumption doesn't match the docs: -> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." +> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." Document each discrepancy clearly. diff --git a/.cursor/rules/guard-git.mdc b/.cursor/rules/guard-git.mdc index 2e7f3fe0..46cb0972 100644 --- a/.cursor/rules/guard-git.mdc +++ b/.cursor/rules/guard-git.mdc @@ -20,7 +20,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf ## Quick start 1. **Scope**: ask project-only vs global (paths differ per product). -2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory. +2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory. 3. **Run `chmod +x`** on `pre-tool-use.sh`. 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys. 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md). diff --git a/.cursor/rules/investigate-bug.mdc b/.cursor/rules/investigate-bug.mdc index 5303748e..0b4816ac 100644 --- a/.cursor/rules/investigate-bug.mdc +++ b/.cursor/rules/investigate-bug.mdc @@ -122,5 +122,5 @@ After writing the bug file, print a one-line summary of the root cause and sugge -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/.cursor/rules/model-domain.mdc b/.cursor/rules/model-domain.mdc index 173fba9e..59380103 100644 --- a/.cursor/rules/model-domain.mdc +++ b/.cursor/rules/model-domain.mdc @@ -211,9 +211,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/.cursor/rules/plan-refactor.mdc b/.cursor/rules/plan-refactor.mdc index 126322ec..1a86072f 100644 --- a/.cursor/rules/plan-refactor.mdc +++ b/.cursor/rules/plan-refactor.mdc @@ -80,7 +80,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/.cursor/rules/plan-release.mdc b/.cursor/rules/plan-release.mdc index 6618eb64..42168881 100644 --- a/.cursor/rules/plan-release.mdc +++ b/.cursor/rules/plan-release.mdc @@ -16,7 +16,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -101,7 +101,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/.cursor/rules/using-bigpowers.mdc b/.cursor/rules/using-bigpowers.mdc index 0acc56df..c68b0922 100644 --- a/.cursor/rules/using-bigpowers.mdc +++ b/.cursor/rules/using-bigpowers.mdc @@ -76,7 +76,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/.cursor/rules/write-document.mdc b/.cursor/rules/write-document.mdc index 1fb7c8ae..5f571a96 100644 --- a/.cursor/rules/write-document.mdc +++ b/.cursor/rules/write-document.mdc @@ -219,7 +219,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -236,7 +236,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/.gemini/extensions/bigpowers/commands/prompts/audit-code.md b/.gemini/extensions/bigpowers/commands/prompts/audit-code.md index 155cafa3..05e063ba 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/audit-code.md +++ b/.gemini/extensions/bigpowers/commands/prompts/audit-code.md @@ -26,7 +26,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. -- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code diff --git a/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md b/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md index 92f1d13f..619271ef 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md +++ b/.gemini/extensions/bigpowers/commands/prompts/craft-skill.md @@ -29,7 +29,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr - Any reference materials to include? - What specs/ output does it produce (if any)? -2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md): +2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md): - Is it atomic (verb-noun)? - Is it "deep" (simple interface, complex internal logic)? - Does it include Hard Gates? @@ -42,7 +42,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source. -4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md). +4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md). > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent. diff --git a/.gemini/extensions/bigpowers/commands/prompts/elaborate-spec.md b/.gemini/extensions/bigpowers/commands/prompts/elaborate-spec.md index 68a1f910..f120d457 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/elaborate-spec.md +++ b/.gemini/extensions/bigpowers/commands/prompts/elaborate-spec.md @@ -62,7 +62,7 @@ Once the user has answered the main questions, probe for assumptions: ### 4. Synthesize and confirm -Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md): +Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md): - The problem (feeds into §1 Business narrative) - The solution and main flow (feeds into §5) - The key constraints and alternative flows (feeds into §6) diff --git a/.gemini/extensions/bigpowers/commands/prompts/evolve-skill.md b/.gemini/extensions/bigpowers/commands/prompts/evolve-skill.md index 0945c0be..b4a1736b 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/evolve-skill.md +++ b/.gemini/extensions/bigpowers/commands/prompts/evolve-skill.md @@ -51,4 +51,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template. **Evidence:** path/to/benchmark-report.md ``` -Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/` +Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path. diff --git a/.gemini/extensions/bigpowers/commands/prompts/grill-me.md b/.gemini/extensions/bigpowers/commands/prompts/grill-me.md index 0598eec8..7d11917f 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/grill-me.md +++ b/.gemini/extensions/bigpowers/commands/prompts/grill-me.md @@ -75,7 +75,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio When an assumption doesn't match the docs: -> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." +> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." Document each discrepancy clearly. diff --git a/.gemini/extensions/bigpowers/commands/prompts/guard-git.md b/.gemini/extensions/bigpowers/commands/prompts/guard-git.md index 76e9d3de..62d4f629 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/guard-git.md +++ b/.gemini/extensions/bigpowers/commands/prompts/guard-git.md @@ -20,7 +20,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf ## Quick start 1. **Scope**: ask project-only vs global (paths differ per product). -2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory. +2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory. 3. **Run `chmod +x`** on `pre-tool-use.sh`. 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys. 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md). diff --git a/.gemini/extensions/bigpowers/commands/prompts/investigate-bug.md b/.gemini/extensions/bigpowers/commands/prompts/investigate-bug.md index 4aab6a23..74b69099 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/investigate-bug.md +++ b/.gemini/extensions/bigpowers/commands/prompts/investigate-bug.md @@ -122,5 +122,5 @@ After writing the bug file, print a one-line summary of the root cause and sugge -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/.gemini/extensions/bigpowers/commands/prompts/model-domain.md b/.gemini/extensions/bigpowers/commands/prompts/model-domain.md index 358f128d..c829626b 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/model-domain.md +++ b/.gemini/extensions/bigpowers/commands/prompts/model-domain.md @@ -211,9 +211,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/.gemini/extensions/bigpowers/commands/prompts/plan-refactor.md b/.gemini/extensions/bigpowers/commands/prompts/plan-refactor.md index 2b6e47ed..4c037f07 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/plan-refactor.md +++ b/.gemini/extensions/bigpowers/commands/prompts/plan-refactor.md @@ -80,7 +80,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/.gemini/extensions/bigpowers/commands/prompts/plan-release.md b/.gemini/extensions/bigpowers/commands/prompts/plan-release.md index 27e39c9c..b8475af7 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/plan-release.md +++ b/.gemini/extensions/bigpowers/commands/prompts/plan-release.md @@ -16,7 +16,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -101,7 +101,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/.gemini/extensions/bigpowers/commands/prompts/using-bigpowers.md b/.gemini/extensions/bigpowers/commands/prompts/using-bigpowers.md index b30b2828..d1092568 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/using-bigpowers.md +++ b/.gemini/extensions/bigpowers/commands/prompts/using-bigpowers.md @@ -76,7 +76,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/.gemini/extensions/bigpowers/commands/prompts/write-document.md b/.gemini/extensions/bigpowers/commands/prompts/write-document.md index d5b15d10..fbf9968f 100644 --- a/.gemini/extensions/bigpowers/commands/prompts/write-document.md +++ b/.gemini/extensions/bigpowers/commands/prompts/write-document.md @@ -219,7 +219,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -236,7 +236,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md b/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md index 9119dc94..9d81721f 100644 --- a/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/audit-code/SKILL.md @@ -28,7 +28,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. -- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code diff --git a/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md b/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md index 7cf7025c..822bd870 100644 --- a/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/craft-skill/SKILL.md @@ -31,7 +31,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr - Any reference materials to include? - What specs/ output does it produce (if any)? -2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md): +2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md): - Is it atomic (verb-noun)? - Is it "deep" (simple interface, complex internal logic)? - Does it include Hard Gates? @@ -44,7 +44,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source. -4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md). +4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md). > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent. diff --git a/.gemini/extensions/bigpowers/skills/elaborate-spec/SKILL.md b/.gemini/extensions/bigpowers/skills/elaborate-spec/SKILL.md index 8c83d40c..afb604b3 100644 --- a/.gemini/extensions/bigpowers/skills/elaborate-spec/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/elaborate-spec/SKILL.md @@ -64,7 +64,7 @@ Once the user has answered the main questions, probe for assumptions: ### 4. Synthesize and confirm -Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md): +Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md): - The problem (feeds into §1 Business narrative) - The solution and main flow (feeds into §5) - The key constraints and alternative flows (feeds into §6) diff --git a/.gemini/extensions/bigpowers/skills/evolve-skill/SKILL.md b/.gemini/extensions/bigpowers/skills/evolve-skill/SKILL.md index 6a07fca4..81608da3 100644 --- a/.gemini/extensions/bigpowers/skills/evolve-skill/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/evolve-skill/SKILL.md @@ -53,4 +53,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template. **Evidence:** path/to/benchmark-report.md ``` -Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/` +Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path. diff --git a/.gemini/extensions/bigpowers/skills/grill-me/SKILL.md b/.gemini/extensions/bigpowers/skills/grill-me/SKILL.md index f1b04208..1aaf93a4 100644 --- a/.gemini/extensions/bigpowers/skills/grill-me/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/grill-me/SKILL.md @@ -77,7 +77,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio When an assumption doesn't match the docs: -> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." +> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." Document each discrepancy clearly. diff --git a/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md b/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md index 8612115f..f6899790 100644 --- a/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/guard-git/SKILL.md @@ -22,7 +22,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf ## Quick start 1. **Scope**: ask project-only vs global (paths differ per product). -2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory. +2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory. 3. **Run `chmod +x`** on `pre-tool-use.sh`. 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys. 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md). diff --git a/.gemini/extensions/bigpowers/skills/investigate-bug/SKILL.md b/.gemini/extensions/bigpowers/skills/investigate-bug/SKILL.md index 540e0063..213e06f5 100644 --- a/.gemini/extensions/bigpowers/skills/investigate-bug/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/investigate-bug/SKILL.md @@ -124,5 +124,5 @@ After writing the bug file, print a one-line summary of the root cause and sugge -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/.gemini/extensions/bigpowers/skills/model-domain/SKILL.md b/.gemini/extensions/bigpowers/skills/model-domain/SKILL.md index 1dac8fff..31a87420 100644 --- a/.gemini/extensions/bigpowers/skills/model-domain/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/model-domain/SKILL.md @@ -213,9 +213,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/.gemini/extensions/bigpowers/skills/plan-refactor/SKILL.md b/.gemini/extensions/bigpowers/skills/plan-refactor/SKILL.md index ceab7990..fec6d55f 100644 --- a/.gemini/extensions/bigpowers/skills/plan-refactor/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/plan-refactor/SKILL.md @@ -82,7 +82,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/.gemini/extensions/bigpowers/skills/plan-release/SKILL.md b/.gemini/extensions/bigpowers/skills/plan-release/SKILL.md index eddb6cbd..c55bf70e 100644 --- a/.gemini/extensions/bigpowers/skills/plan-release/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/plan-release/SKILL.md @@ -18,7 +18,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -103,7 +103,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/.gemini/extensions/bigpowers/skills/using-bigpowers/SKILL.md b/.gemini/extensions/bigpowers/skills/using-bigpowers/SKILL.md index 66251f78..13ea6b78 100644 --- a/.gemini/extensions/bigpowers/skills/using-bigpowers/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/using-bigpowers/SKILL.md @@ -78,7 +78,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/.gemini/extensions/bigpowers/skills/write-document/SKILL.md b/.gemini/extensions/bigpowers/skills/write-document/SKILL.md index 453188c1..41d08f56 100644 --- a/.gemini/extensions/bigpowers/skills/write-document/SKILL.md +++ b/.gemini/extensions/bigpowers/skills/write-document/SKILL.md @@ -221,7 +221,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -238,7 +238,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/.pi/prompts/audit-code.md b/.pi/prompts/audit-code.md index 155cafa3..05e063ba 100644 --- a/.pi/prompts/audit-code.md +++ b/.pi/prompts/audit-code.md @@ -26,7 +26,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. -- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code diff --git a/.pi/prompts/craft-skill.md b/.pi/prompts/craft-skill.md index 92f1d13f..619271ef 100644 --- a/.pi/prompts/craft-skill.md +++ b/.pi/prompts/craft-skill.md @@ -29,7 +29,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr - Any reference materials to include? - What specs/ output does it produce (if any)? -2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md): +2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md): - Is it atomic (verb-noun)? - Is it "deep" (simple interface, complex internal logic)? - Does it include Hard Gates? @@ -42,7 +42,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source. -4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md). +4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md). > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent. diff --git a/.pi/prompts/elaborate-spec.md b/.pi/prompts/elaborate-spec.md index 68a1f910..f120d457 100644 --- a/.pi/prompts/elaborate-spec.md +++ b/.pi/prompts/elaborate-spec.md @@ -62,7 +62,7 @@ Once the user has answered the main questions, probe for assumptions: ### 4. Synthesize and confirm -Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md): +Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md): - The problem (feeds into §1 Business narrative) - The solution and main flow (feeds into §5) - The key constraints and alternative flows (feeds into §6) diff --git a/.pi/prompts/evolve-skill.md b/.pi/prompts/evolve-skill.md index 0945c0be..b4a1736b 100644 --- a/.pi/prompts/evolve-skill.md +++ b/.pi/prompts/evolve-skill.md @@ -51,4 +51,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template. **Evidence:** path/to/benchmark-report.md ``` -Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/` +Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path. diff --git a/.pi/prompts/grill-me.md b/.pi/prompts/grill-me.md index 0598eec8..7d11917f 100644 --- a/.pi/prompts/grill-me.md +++ b/.pi/prompts/grill-me.md @@ -75,7 +75,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio When an assumption doesn't match the docs: -> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." +> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." Document each discrepancy clearly. diff --git a/.pi/prompts/guard-git.md b/.pi/prompts/guard-git.md index 76e9d3de..62d4f629 100644 --- a/.pi/prompts/guard-git.md +++ b/.pi/prompts/guard-git.md @@ -20,7 +20,7 @@ Installs a shared hook that blocks destructive git operations and enforces workf ## Quick start 1. **Scope**: ask project-only vs global (paths differ per product). -2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory. +2. **Write the hook bundle** from [REFERENCE.md](REFERENCE.md) into the client's hooks directory. 3. **Run `chmod +x`** on `pre-tool-use.sh`. 4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys. 5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md). diff --git a/.pi/prompts/investigate-bug.md b/.pi/prompts/investigate-bug.md index 4aab6a23..74b69099 100644 --- a/.pi/prompts/investigate-bug.md +++ b/.pi/prompts/investigate-bug.md @@ -122,5 +122,5 @@ After writing the bug file, print a one-line summary of the root cause and sugge -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/.pi/prompts/model-domain.md b/.pi/prompts/model-domain.md index 358f128d..c829626b 100644 --- a/.pi/prompts/model-domain.md +++ b/.pi/prompts/model-domain.md @@ -211,9 +211,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/.pi/prompts/plan-refactor.md b/.pi/prompts/plan-refactor.md index 2b6e47ed..4c037f07 100644 --- a/.pi/prompts/plan-refactor.md +++ b/.pi/prompts/plan-refactor.md @@ -80,7 +80,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/.pi/prompts/plan-release.md b/.pi/prompts/plan-release.md index 27e39c9c..b8475af7 100644 --- a/.pi/prompts/plan-release.md +++ b/.pi/prompts/plan-release.md @@ -16,7 +16,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -101,7 +101,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/.pi/prompts/using-bigpowers.md b/.pi/prompts/using-bigpowers.md index b30b2828..d1092568 100644 --- a/.pi/prompts/using-bigpowers.md +++ b/.pi/prompts/using-bigpowers.md @@ -76,7 +76,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/.pi/prompts/write-document.md b/.pi/prompts/write-document.md index d5b15d10..fbf9968f 100644 --- a/.pi/prompts/write-document.md +++ b/.pi/prompts/write-document.md @@ -219,7 +219,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -236,7 +236,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/.pi/skills/audit-code/SKILL.md b/.pi/skills/audit-code/SKILL.md index e7417a7f..91da927f 100644 --- a/.pi/skills/audit-code/SKILL.md +++ b/.pi/skills/audit-code/SKILL.md @@ -27,7 +27,7 @@ Apply the full checklist to churn-ranked files in descending order. Files with z - Default: full checklist - --quick: Run only Supply Chain and Test Coverage. Use for changes under 50 LOC. - --gate: Non-interactive mode for automated CI gating (used by build-epic step 6). Exit with non-zero status code (`exit 1`) on ANY checklist failure; `exit 0` only if ALL items pass. Produces a compact pass/fail summary to stderr. On failure, list every ✗ item with reason. -- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree. See [REFERENCE.md](REFERENCE.md) or: +- --parallel: Run checklist sections in **isolated git worktrees** (e45s18) so concurrent checks cannot corrupt each other's working tree: ```bash bash scripts/lib/parallel-review-worktrees.sh audit-code diff --git a/.pi/skills/change-request/SKILL.md b/.pi/skills/change-request/SKILL.md index 767d3c5f..fcb6a505 100644 --- a/.pi/skills/change-request/SKILL.md +++ b/.pi/skills/change-request/SKILL.md @@ -31,7 +31,7 @@ Intake a new requirement mid-flight without disrupting work in progress. Value-engineering pass over the full release using WSJF. -See [REFERENCE.md](REFERENCE.md) for the full WSJF scoring rubric. +See [REFERENCE.md](../../../skills/change-request/REFERENCE.md) for the full WSJF scoring rubric. 1. **Score** each epic/story: BV + TC + RR / Job Size. 2. **Re-sort** `release-plan.yaml` `epics[]` and per-epic `wsjf` fields. diff --git a/.pi/skills/commit-message/SKILL.md b/.pi/skills/commit-message/SKILL.md index bbf901f7..093bf6cf 100644 --- a/.pi/skills/commit-message/SKILL.md +++ b/.pi/skills/commit-message/SKILL.md @@ -24,7 +24,7 @@ description: "Reviews working-tree changes, then drafts a Conventional Commits t 1. **Inventory** — List changed paths; group by feature vs chore vs docs vs test-only. 2. **Decide commit shape** — One atomic commit is ideal. If the diff mixes unrelated concerns, recommend **multiple commits** (each with its own type/scope) before suggesting one message. 3. **Classify for semantic release** — `fix` → patch, `feat` → minor, **breaking** → major. -4. **Write the message** — `type(optional-scope)!: description` (see [REFERENCE.md](REFERENCE.md#message-format)). Use `!` or a `BREAKING CHANGE:` footer when behavior contracts change. +4. **Write the message** — `type(optional-scope)!: description` (see [REFERENCE.md](../../../skills/commit-message/REFERENCE.md#message-format)). Use `!` or a `BREAKING CHANGE:` footer when behavior contracts change. 5. **Note defensive-code categories touched** — from CONVENTIONS.md: Rate limit | Retry with backoff | Circuit breaker | Timeout | Graceful degradation 6. **Note fix-ratio contribution** — Each `fix:` commit counts toward `metrics.commit_ratio.fix` in `specs/state.yaml`. After `release-branch`, `session-state` recalculates the ratio automatically. A high fix rate (>30%) triggers a deploy + smoke-test suggestion. 7. **Deliver** — Output: @@ -42,11 +42,11 @@ description: "Reviews working-tree changes, then drafts a Conventional Commits t ## When not to invent a bump -If the repo uses a custom `@semantic-release/commit-analyzer` preset, note that your bump is **heuristic** and they should match `.releaserc` / `release.config.*`. See [REFERENCE.md](REFERENCE.md#custom-repositories). +If the repo uses a custom `@semantic-release/commit-analyzer` preset, note that your bump is **heuristic** and they should match `.releaserc` / `release.config.*`. See [REFERENCE.md](../../../skills/commit-message/REFERENCE.md#custom-repositories). ## Further reading -- [REFERENCE.md](REFERENCE.md) — Message shape, footers, release mapping, squashing notes. +- [REFERENCE.md](../../../skills/commit-message/REFERENCE.md) — Message shape, footers, release mapping, squashing notes. diff --git a/.pi/skills/compose-workflow/SKILL.md b/.pi/skills/compose-workflow/SKILL.md index 68203b28..e006743b 100644 --- a/.pi/skills/compose-workflow/SKILL.md +++ b/.pi/skills/compose-workflow/SKILL.md @@ -63,7 +63,7 @@ Add to `AGENTS.md`: → verify: `ls specs/workflows/*.yaml 2>/dev/null | wc -l | awk '{if($1>=8) print "OK: " $1 " recipes"; else print "FAIL"}'` -See [REFERENCE.md](REFERENCE.md) for template. +See [REFERENCE.md](../../../skills/compose-workflow/REFERENCE.md) for template. --- diff --git a/.pi/skills/craft-skill/SKILL.md b/.pi/skills/craft-skill/SKILL.md index 8bd37eab..92ddca78 100644 --- a/.pi/skills/craft-skill/SKILL.md +++ b/.pi/skills/craft-skill/SKILL.md @@ -30,20 +30,20 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr - Any reference materials to include? - What specs/ output does it produce (if any)? -2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](../docs/PRINCIPLES.md): +2. **Verify Principles** — Ensure the skill aligns with [PRINCIPLES.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/PRINCIPLES.md): - Is it atomic (verb-noun)? - Is it "deep" (simple interface, complex internal logic)? - Does it include Hard Gates? - Is it verifiable with a `.feature` file? 3. **Draft the skill** — create: - - SKILL.md with concise instructions (see [REFERENCE.md](REFERENCE.md) for template) + - SKILL.md with concise instructions (see [REFERENCE.md](../../../skills/craft-skill/REFERENCE.md) for template) - Additional reference files if content exceeds 100 lines - Utility scripts if deterministic operations needed **Auto-skill from library README:** When user provides a library README or API docs URL, extract: triggers, HARD GATEs, verify commands, specs/ output — draft SKILL.md without inventing APIs not in the source. -4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](../docs/references/model-profiles.md). +4. Add `model:` frontmatter (`haiku` | `sonnet` | `opus`) per [model-profiles.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/model-profiles.md). > **STREAM CONTINUITY** — When writing file content, output in continuous chunks of ~200 lines. Do not pause. Continue immediately until complete. If you need time, emit a placeholder comment rather than going silent. @@ -60,7 +60,7 @@ Move process detail into the SKILL.md body or REFERENCE.md — never into `descr ## Naming Rules -Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](REFERENCE.md) for full rules, examples, and documented exceptions. +Every skill name must be a **two-word verb-noun pair**. See [REFERENCE.md](../../../skills/craft-skill/REFERENCE.md) for full rules, examples, and documented exceptions. ## specs/ Output diff --git a/.pi/skills/deepen-architecture/SKILL.md b/.pi/skills/deepen-architecture/SKILL.md index 78daa8a1..0cb0eb5f 100644 --- a/.pi/skills/deepen-architecture/SKILL.md +++ b/.pi/skills/deepen-architecture/SKILL.md @@ -14,7 +14,7 @@ Surface architectural friction and propose **deepening opportunities** — refac ## Glossary -Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](LANGUAGE.md). +Use these terms exactly in every suggestion. Consistent language is the point — don't drift into "component," "service," "API," or "boundary." Full definitions in [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md). - **Module** — anything with an interface and an implementation (function, class, package, slice). - **Interface** — everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature. @@ -25,13 +25,13 @@ Use these terms exactly in every suggestion. Consistent language is the point - **Leverage** — what callers get from depth. - **Locality** — what maintainers get from depth: change, bugs, knowledge concentrated in one place. -Key principles (see [LANGUAGE.md](LANGUAGE.md) for the full list): +Key principles (see [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md) for the full list): - **Deletion test**: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep. - **The interface is the test surface.** - **One adapter = hypothetical seam. Two adapters = real seam.** -This skill is _informed_ by the project's domain model — `specs/tech-architecture/tech-stack.md` and any `specs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). +This skill is _informed_ by the project's domain model — `specs/tech-architecture/tech-stack.md` and any `specs/adr/`. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See [CONTEXT-FORMAT.md](../../../skills/model-domain/CONTEXT-FORMAT.md) and [ADR-FORMAT.md](../../../skills/model-domain/ADR-FORMAT.md). ## Process @@ -81,7 +81,7 @@ Present a numbered list of deepening opportunities. For each candidate: - **Solution** — plain English description of what would change - **Benefits** — explained in terms of locality and leverage, and how tests would improve -**Use `specs/tech-architecture/tech-stack.md` vocabulary for the domain, and [LANGUAGE.md](LANGUAGE.md) vocabulary for the architecture.** +**Use `specs/tech-architecture/tech-stack.md` vocabulary for the domain, and [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md) vocabulary for the architecture.** **ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly. Don't list every theoretical refactor an ADR forbids. @@ -93,10 +93,10 @@ Once the user picks a candidate, drop into a grilling conversation. Walk the des Side effects happen inline as decisions crystallize: -- **Naming a deepened module after a concept not in `specs/tech-architecture/tech-stack.md`?** Add the term to `specs/tech-architecture/tech-stack.md` — same discipline as `model-domain` (see [CONTEXT-FORMAT.md](../model-domain/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. +- **Naming a deepened module after a concept not in `specs/tech-architecture/tech-stack.md`?** Add the term to `specs/tech-architecture/tech-stack.md` — same discipline as `model-domain` (see [CONTEXT-FORMAT.md](../../../skills/model-domain/CONTEXT-FORMAT.md)). Create the file lazily if it doesn't exist. - **Sharpening a fuzzy term during the conversation?** Update `specs/tech-architecture/tech-stack.md` right there. -- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../model-domain/ADR-FORMAT.md). -- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](INTERFACE-DESIGN.md). +- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer. See [ADR-FORMAT.md](../../../skills/model-domain/ADR-FORMAT.md). +- **Want to explore alternative interfaces for the deepened module?** See [INTERFACE-DESIGN.md](../../../skills/deepen-architecture/INTERFACE-DESIGN.md). ### 5. Import-boundary hygiene (e45s14) @@ -120,7 +120,7 @@ Run the check before proposing cross-module `source` edges. Convention docs alon # Deepening -How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. +How to deepen a cluster of shallow modules safely, given its dependencies. Assumes the vocabulary in [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**. ## Dependency categories @@ -162,7 +162,7 @@ Third-party services (Stripe, Twilio, etc.) you don't control. The deepened modu When the user wants to explore alternative interfaces for a chosen deepening candidate, use this parallel sub-agent pattern. Based on "Design It Twice" (Ousterhout) — your first idea is unlikely to be the best. -Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. +Uses the vocabulary in [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md) — **module**, **interface**, **seam**, **adapter**, **leverage**. ## Process @@ -171,7 +171,7 @@ Uses the vocabulary in [LANGUAGE.md](LANGUAGE.md) — **module**, **interface**, Before spawning sub-agents, write a user-facing explanation of the problem space for the chosen candidate: - The constraints any new interface would need to satisfy -- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](DEEPENING.md)) +- The dependencies it would rely on, and which category they fall into (see [DEEPENING.md](../../../skills/deepen-architecture/DEEPENING.md)) - A rough illustrative code sketch to ground the constraints — not a proposal, just a way to make the constraints concrete Show this to the user, then immediately proceed to Step 2. The user reads and thinks while the sub-agents work in parallel. @@ -180,21 +180,21 @@ Show this to the user, then immediately proceed to Step 2. The user reads and th Spawn 3+ sub-agents in parallel using the Agent tool. Each must produce a **radically different** interface for the deepened module. -Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: +Prompt each sub-agent with a separate technical brief (file paths, coupling details, dependency category from [DEEPENING.md](../../../skills/deepen-architecture/DEEPENING.md), what sits behind the seam). The brief is independent of the user-facing problem-space explanation in Step 1. Give each agent a different design constraint: - Agent 1: "Minimize the interface — aim for 1–3 entry points max. Maximise leverage per entry point." - Agent 2: "Maximise flexibility — support many use cases and extension." - Agent 3: "Optimise for the most common caller — make the default case trivial." - Agent 4 (if applicable): "Design around ports & adapters for cross-seam dependencies." -Include both [LANGUAGE.md](LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. +Include both [LANGUAGE.md](../../../skills/deepen-architecture/LANGUAGE.md) vocabulary and CONTEXT.md vocabulary in the brief so each sub-agent names things consistently with the architecture language and the project's domain language. Each sub-agent outputs: 1. Interface (types, methods, params — plus invariants, ordering, error modes) 2. Usage example showing how callers use it 3. What the implementation hides behind the seam -4. Dependency strategy and adapters (see [DEEPENING.md](DEEPENING.md)) +4. Dependency strategy and adapters (see [DEEPENING.md](../../../skills/deepen-architecture/DEEPENING.md)) 5. Trade-offs — where leverage is high, where it's thin ### 3. Present and compare diff --git a/.pi/skills/deploy/SKILL.md b/.pi/skills/deploy/SKILL.md index 1d79cff1..080525d9 100644 --- a/.pi/skills/deploy/SKILL.md +++ b/.pi/skills/deploy/SKILL.md @@ -87,15 +87,15 @@ exit 1 After invoking the deploy command, poll for completion: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/deploy/REFERENCE.md) Use exponential backoff for retries on transient failures: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/deploy/REFERENCE.md) ### 6. Baseline smoke test -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/deploy/REFERENCE.md) For comprehensive health-checking, chain to the `smoke-test` skill: @@ -106,7 +106,7 @@ bash scripts/run-smoke.sh "$DEPLOY_URL" ### 7. Three-independent-facts verification (e45s15) -Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](REFERENCE.md#three-independent-facts). +Before declaring deploy success, verify **three independent facts** — build artifact, platform accept, live/registry reachability. See [REFERENCE.md](../../../skills/deploy/REFERENCE.md#three-independent-facts). ## Verify diff --git a/.pi/skills/develop-tdd/SKILL.md b/.pi/skills/develop-tdd/SKILL.md index 941362bf..a61dc684 100644 --- a/.pi/skills/develop-tdd/SKILL.md +++ b/.pi/skills/develop-tdd/SKILL.md @@ -14,7 +14,7 @@ description: "Test-driven development with red-green-refactor loop using vertica ## Philosophy -Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail. +Tests verify behavior through public interfaces, not implementation details. A good test reads like a specification. See [REFERENCE.md](../../../skills/develop-tdd/REFERENCE.md) for the horizontal-slice anti-pattern and TDD phase detail. ## Red Flags @@ -40,7 +40,7 @@ If you catch yourself thinking these, stop and reconsider — you are likely dev - [ ] Read active `specs/epics/*/epic.yaml` story tasks or `specs/bugs/BUG-*.md` — understand verify steps - [ ] If `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` exists for the active epic, read it before writing the first test. Implement P0 scenarios (`SC-*-P0-*`) before P1. P2/P3 scenarios are optional per time budget. - [ ] Confirm interface changes and behaviors to test (prioritize) -- [ ] Design interfaces for testability — identify [deep modules](deep-modules.md) opportunities +- [ ] Design interfaces for testability — identify [deep modules](../../../skills/develop-tdd/deep-modules.md) opportunities - [ ] Get user approval on the plan Apply the **enforce-first** F.I.R.S.T rubric: Fast, Independent, Repeatable, Self-Validating, Timely. @@ -74,7 +74,7 @@ For each remaining behavior: RED → GREEN → REFACTOR (optional). One test at ### 4. Visual Slices (UI alternate workflow) -For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See [REFERENCE.md](REFERENCE.md) for the full Visual Slices procedure. +For UI components where behavioral unit testing is brittle: extract logic into a Controller/ViewModel/Hook (pure TDD), then use Visual Slices for the View layer. See [REFERENCE.md](../../../skills/develop-tdd/REFERENCE.md) for the full Visual Slices procedure. ### 5. Refactor @@ -91,7 +91,7 @@ Once all tests pass: locate the Verification Script in the active epic capsule, ### 6a. CI dry-run sub-step -If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](REFERENCE.md#ci-dry-run). +If this cycle modified files in `.github/workflows/`, run the CI dry-run procedure documented in [REFERENCE.md](../../../skills/develop-tdd/REFERENCE.md#ci-dry-run). ## Checklist Per Cycle @@ -149,7 +149,7 @@ RIGHT (vertical): ... ``` -> The Red Flags table lives in [SKILL.md](SKILL.md#red-flags) — it is core behavioral guidance, not reference detail. +> The Red Flags table lives in [SKILL.md](../../../skills/develop-tdd/SKILL.md#red-flags) — it is core behavioral guidance, not reference detail. ## TDD Phases (Detail) diff --git a/.pi/skills/elaborate-spec/SKILL.md b/.pi/skills/elaborate-spec/SKILL.md index 9a8ac603..906c64fa 100644 --- a/.pi/skills/elaborate-spec/SKILL.md +++ b/.pi/skills/elaborate-spec/SKILL.md @@ -63,7 +63,7 @@ Once the user has answered the main questions, probe for assumptions: ### 4. Synthesize and confirm -Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md): +Summarize your understanding in 3–5 bullet points aligned with [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md): - The problem (feeds into §1 Business narrative) - The solution and main flow (feeds into §5) - The key constraints and alternative flows (feeds into §6) diff --git a/.pi/skills/evolve-skill/SKILL.md b/.pi/skills/evolve-skill/SKILL.md index f73c20e4..f8e79f40 100644 --- a/.pi/skills/evolve-skill/SKILL.md +++ b/.pi/skills/evolve-skill/SKILL.md @@ -34,7 +34,7 @@ description: "Benchmark-gated skill evolution — consume bigpowers-benchmark re → verify: `grep -c 'run-benchmark\|pass_at_k\|BASELINE-' skills/evolve-skill/SKILL.md | awk '{if($1>=2) print "OK"; else print "FAIL"}'` -See [REFERENCE.md](REFERENCE.md) for ADR template. +See [REFERENCE.md](../../../skills/evolve-skill/REFERENCE.md) for ADR template. @@ -52,4 +52,4 @@ See [REFERENCE.md](REFERENCE.md) for ADR template. **Evidence:** path/to/benchmark-report.md ``` -Benchmark repo: `/Users/danielvm/Developer/bigpowers-benchmark/` +Benchmark repo: `bigpowers-benchmark` — resolve the local clone on this machine (e.g. `gh repo clone danielvm-git/bigpowers-benchmark` if absent); never assume a hard-coded absolute path. diff --git a/.pi/skills/extract-design/SKILL.md b/.pi/skills/extract-design/SKILL.md index b7c9407b..ded1383f 100644 --- a/.pi/skills/extract-design/SKILL.md +++ b/.pi/skills/extract-design/SKILL.md @@ -74,7 +74,7 @@ node extract-design/scripts/extract.js --lint-only node extract-design/tests/test-extraction.js ``` -See [REFERENCE.md](REFERENCE.md) for extraction algorithms and heuristics. +See [REFERENCE.md](../../../skills/extract-design/REFERENCE.md) for extraction algorithms and heuristics. --- diff --git a/.pi/skills/generate-allure-report/SKILL.md b/.pi/skills/generate-allure-report/SKILL.md index bb548623..f5134150 100644 --- a/.pi/skills/generate-allure-report/SKILL.md +++ b/.pi/skills/generate-allure-report/SKILL.md @@ -26,7 +26,7 @@ Three files in `allure-results/`: ## Data Sources -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/generate-allure-report/REFERENCE.md) ## Verify diff --git a/.pi/skills/grill-me/SKILL.md b/.pi/skills/grill-me/SKILL.md index ed51ff64..d6ec0393 100644 --- a/.pi/skills/grill-me/SKILL.md +++ b/.pi/skills/grill-me/SKILL.md @@ -20,7 +20,7 @@ If a question can be answered by exploring the codebase, explore it instead. ## Docs mode -Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](REFERENCE.md) for the full process. +Ground every challenge in real documentation — no assumption about a library's behavior goes unchecked. See [REFERENCE.md](../../../skills/grill-me/REFERENCE.md) for the full process. Short form: 1. List every external library, third-party API, and framework behavior relied upon. @@ -76,7 +76,7 @@ Ask one question at a time. For each challenge, cite the specific URL and sectio When an assumption doesn't match the docs: -> "Your plan uses `library.doThing(a, b)` but the [docs](URL) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." +> "Your plan uses `library.doThing(a, b)` but the [docs](https://example.com/api-reference) show the signature is `doThing(config: {a, b})` with a config object. This will fail at runtime." Document each discrepancy clearly. diff --git a/.pi/skills/grill-with-docs/SKILL.md b/.pi/skills/grill-with-docs/SKILL.md index 03d004b3..6fc6de34 100644 --- a/.pi/skills/grill-with-docs/SKILL.md +++ b/.pi/skills/grill-with-docs/SKILL.md @@ -27,7 +27,7 @@ description: "Doc-grounded variant of grill-me — stress-tests plan assumptions → verify: `grep -c 'https\?://' skills/grill-with-docs/SKILL.md | awk '{if($1>=2) print "OK"; else print "NEEDS DOCS"}'` -See [REFERENCE.md](REFERENCE.md) for question templates. +See [REFERENCE.md](../../../skills/grill-with-docs/REFERENCE.md) for question templates. diff --git a/.pi/skills/guard-git/SKILL.md b/.pi/skills/guard-git/SKILL.md index 6e18eea1..6b314caa 100644 --- a/.pi/skills/guard-git/SKILL.md +++ b/.pi/skills/guard-git/SKILL.md @@ -16,15 +16,15 @@ Installs a shared hook that blocks destructive git operations and enforces workf - **Discipline**: Blocks direct commits or pushes to protected branches (`main`, `master`) unless `GIT_BIGPOWERS_LAND=1` (set only by `scripts/land-branch.sh`). - **Allows**: `git push origin ` for backup/CI; solo land push to `main` only inside `land-branch.sh`. - **Standardization**: Enforces [Conventional Commits](https://www.conventionalcommits.org/) for all `git commit` commands. -- **Secrets**: Blocks commits containing common secret patterns (`sk-`, `ghp_`, `AKIA`, `xoxb-`, `-----BEGIN` private keys) — see [REFERENCE.md](REFERENCE.md). +- **Secrets**: Blocks commits containing common secret patterns (`sk-`, `ghp_`, `AKIA`, `xoxb-`, `-----BEGIN` private keys) — see [REFERENCE.md](../../../skills/guard-git/REFERENCE.md). ## Quick start 1. **Scope**: ask project-only vs global (paths differ per product). -2. **Copy the hook bundle** from the root [hooks/](hooks/) directory to the client's hooks directory. +2. **Write the hook bundle** from [REFERENCE.md](../../../skills/guard-git/REFERENCE.md) into the client's hooks directory. 3. **Run `chmod +x`** on `pre-tool-use.sh`. -4. **Merge** the hook snippet from [REFERENCE.md](REFERENCE.md) into the right settings file — do not wipe unrelated keys. -5. **Verify** with the tests in [REFERENCE.md](REFERENCE.md). +4. **Merge** the hook snippet from [REFERENCE.md](../../../skills/guard-git/REFERENCE.md) into the right settings file — do not wipe unrelated keys. +5. **Verify** with the tests in [REFERENCE.md](../../../skills/guard-git/REFERENCE.md). | Client | Mechanism | Config | |--------|-----------|--------| @@ -41,7 +41,7 @@ To add or remove patterns or protected branches, edit `pre-tool-use.sh`. ## Advanced -Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](REFERENCE.md). +Full JSON examples, merge rules, Antigravity deny-list entries, and test commands: [REFERENCE.md](../../../skills/guard-git/REFERENCE.md). diff --git a/.pi/skills/harden-vps/SKILL.md b/.pi/skills/harden-vps/SKILL.md index ff14f18a..8306eee1 100644 --- a/.pi/skills/harden-vps/SKILL.md +++ b/.pi/skills/harden-vps/SKILL.md @@ -6,7 +6,7 @@ description: "Harden a production Linux VPS for BigBase across three layers — # Harden VPS -Three-layer production hardening for BigBase on Contabo VPS. Each layer independently verifiable. Apply OS first (firewall blocks attacks immediately), then BigBase (alerts + backups), then Contabo (snapshots). See [REFERENCE.md](REFERENCE.md) for full script bodies, systemd unit template, and gotchas. +Three-layer production hardening for BigBase on Contabo VPS. Each layer independently verifiable. Apply OS first (firewall blocks attacks immediately), then BigBase (alerts + backups), then Contabo (snapshots). See [REFERENCE.md](../../../skills/harden-vps/REFERENCE.md) for full script bodies, systemd unit template, and gotchas. ## Quick start diff --git a/.pi/skills/investigate-bug/SKILL.md b/.pi/skills/investigate-bug/SKILL.md index 0c9f610b..ca1608bb 100644 --- a/.pi/skills/investigate-bug/SKILL.md +++ b/.pi/skills/investigate-bug/SKILL.md @@ -123,5 +123,5 @@ After writing the bug file, print a one-line summary of the root cause and sugge -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/.pi/skills/migrate-spec/SKILL.md b/.pi/skills/migrate-spec/SKILL.md index 364f1413..36d2b8db 100644 --- a/.pi/skills/migrate-spec/SKILL.md +++ b/.pi/skills/migrate-spec/SKILL.md @@ -56,13 +56,13 @@ If none found: ask the user which framework before proceeding. List every artifact found matching the detected framework. Present the list to the user: -See [REFERENCE.md](REFERENCE.md) — `Detected: GSD...` +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) — `Detected: GSD...` → verify: `find . -maxdepth 4 \( -name "ROADMAP.md" -o -name "spec.md" -o -name "prd.md" -o -name "REQUIREMENTS.md" \) 2>/dev/null | grep -v ".git" | head -15` ### Step 3 — Transform (one artifact at a time, show diffs) -Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./REFERENCE-GSD.md). For each target file: +Apply the mapping from [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) and [REFERENCE-GSD.md](../../../skills/migrate-spec/REFERENCE-GSD.md). For each target file: 1. Show what will be created or appended (title + first 20 lines). 2. Ask: "Create this? [yes / edit / skip]" @@ -72,25 +72,25 @@ Apply the mapping from [REFERENCE.md](./REFERENCE.md) and [REFERENCE-GSD.md](./R When source artifacts contain IDs (REQ-XX, FR-XX, UJ-XX), emit them as **first-class YAML fields** in `in_scope` entries, not YAML comments: -See [REFERENCE.md](REFERENCE.md) — `# CORRECT — first-class id: field...` +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) — `# CORRECT — first-class id: field...` **When source has no IDs:** Prompt the user: "No IDs found. Assign auto-generated IDs? [yes / no]". If yes, emit `REQ-{NNN}` with `# auto-generated` annotation. **When source has MIXED IDs:** Items with IDs get `id:` fields; items without IDs receive auto-generated `REQ-NNN` entries. Document which were auto-generated in a comment block at the top of `in_scope`. -See [REFERENCE.md — in_scope format with ID tracking](./REFERENCE.md#in_scope-format-with-id-tracking) for examples. +See [REFERENCE.md — in_scope format with ID tracking](../../../skills/migrate-spec/REFERENCE.md#in_scope-format-with-id-tracking) for examples. #### Traceability Output (FR-XX, UJ-XX) When source has FR-XX or UJ-XX IDs, emit `specs/product/REQUIREMENTS_TRACE.yaml` for end-to-end requirement traceability: -See [REFERENCE.md](REFERENCE.md) — `trace:...` +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) — `trace:...` **Existing trace file:** If `REQUIREMENTS_TRACE.yaml` already exists, prompt: "REQUIREMENTS_TRACE.yaml exists. [overwrite / merge / skip]" **No FR-XX/UJ-XX found:** Skip trace file; add note to state.yaml handoff: "No FR-XX/UJ-XX IDs found — traceability file skipped". -See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirements_traceyaml-format) for the complete schema. +See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](../../../skills/migrate-spec/REFERENCE.md#requirements_traceyaml-format) for the complete schema. > **HARD GATE** — Never overwrite an existing `specs/` file without explicit user confirmation. Merge into it if it exists; don't clobber. > @@ -102,11 +102,11 @@ See [REFERENCE.md — REQUIREMENTS_TRACE.yaml format](./REFERENCE.md#requirement Always regenerate `specs/state.yaml` from scratch in bigpowers YAML format (see REFERENCE.md for template). The **handoff block is mandatory** and must include all four fields: -See [REFERENCE.md](REFERENCE.md) — `active_flow: null...` +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) — `active_flow: null...` If no open decisions were found during migration, the `open_decisions` list may be empty with an explanatory comment: -See [REFERENCE.md](REFERENCE.md) — `handoff:...` +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) — `handoff:...` → verify: `grep -q 'handoff:' specs/state.yaml && grep -q 'last_step_completed' specs/state.yaml && echo "ok" || echo "MISSING or INCOMPLETE: handoff block"` @@ -116,7 +116,7 @@ See [REFERENCE.md](REFERENCE.md) — `handoff:...` Full artifact transformation rules for migrating GSD projects to bigpowers YAML layout. -See [REFERENCE.md](./REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats. +See [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) for spec-kit, BMAD, learnings, and ADR/DECISION-LOG formats. --- @@ -162,7 +162,7 @@ Transform: GSD REQUIREMENTS has: REQ-XX IDs, Validated/Active/Out-of-Scope categories, traceability. Transform: -- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](./REFERENCE.md#in_scope-format-with-id-tracking)) +- Preserve REQ-XX IDs as **first-class `id:` fields** in `in_scope` entries (see [REFERENCE.md — ID tracking format](../../../skills/migrate-spec/REFERENCE.md#in_scope-format-with-id-tracking)) - Validated requirements → `in_scope` entries with `id:`, `description:`, `source:` fields - Out-of-Scope → `out_of_scope` entries (preserve IDs if present) - Active (in-progress) → `in_scope` with status note @@ -264,7 +264,7 @@ These GSD artifacts are not migrated — they are execution records, not plannin Transformation rules for spec-kit and BMAD projects, plus learnings to adopt and output formats. -See [REFERENCE-GSD.md](./REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping. +See [REFERENCE-GSD.md](../../../skills/migrate-spec/REFERENCE-GSD.md) for full GSD → bigpowers YAML mapping. --- @@ -776,7 +776,7 @@ If **no**, skip. Add note to handoff: "Methodology doc: skipped — can be added ## Artifact Mapping Summary -Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE.md](./REFERENCE.md) (spec-kit, BMAD, learnings). +Full mapping tables: [REFERENCE-GSD.md](../../../skills/migrate-spec/REFERENCE-GSD.md) (GSD) · [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md) (spec-kit, BMAD, learnings). | Source | Target | |--------|--------| @@ -814,7 +814,7 @@ Full mapping tables: [REFERENCE-GSD.md](./REFERENCE-GSD.md) (GSD) · [REFERENCE. After migration, offer the user a brief analysis of what the source framework did that bigpowers doesn't have yet. -Use the learnings table from [REFERENCE.md](./REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt. +Use the learnings table from [REFERENCE.md](../../../skills/migrate-spec/REFERENCE.md#learnings-to-adopt). Present as checkboxes so the user can decide which to adopt. → verify: `grep -c "\- \[ \]" specs/state.yaml 2>/dev/null && echo "pending items recorded" || echo "no pending items in state.yaml"` diff --git a/.pi/skills/model-domain/SKILL.md b/.pi/skills/model-domain/SKILL.md index c25ebc55..e2dd2ab3 100644 --- a/.pi/skills/model-domain/SKILL.md +++ b/.pi/skills/model-domain/SKILL.md @@ -74,7 +74,7 @@ When the user states how something works, check whether the code agrees. If you ### Update specs/tech-architecture/tech-stack.md inline -When a term is resolved, update `specs/tech-architecture/tech-stack.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](./CONTEXT-FORMAT.md). +When a term is resolved, update `specs/tech-architecture/tech-stack.md` right there. Don't batch these up — capture them as they happen. Use the format in [CONTEXT-FORMAT.md](../../../skills/model-domain/CONTEXT-FORMAT.md). Don't couple `specs/tech-architecture/tech-stack.md` to implementation details. Only include terms that are meaningful to domain experts. @@ -86,7 +86,7 @@ Only offer to create an ADR when all three are true: 2. **Surprising without context** — a future reader will wonder "why did they do it this way?" 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons -If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](./ADR-FORMAT.md). +If any of the three is missing, skip the ADR. Use the format in [ADR-FORMAT.md](../../../skills/model-domain/ADR-FORMAT.md). ## Concurrency safety audit @@ -212,9 +212,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/.pi/skills/orchestrate-project/SKILL.md b/.pi/skills/orchestrate-project/SKILL.md index 8a85c406..dc125bed 100644 --- a/.pi/skills/orchestrate-project/SKILL.md +++ b/.pi/skills/orchestrate-project/SKILL.md @@ -40,7 +40,7 @@ Track progress via `specs/state.yaml` `project_cycle`: - `handoff.next_skill`: skill for the current phase - On resume, read `project_cycle.current_phase` and continue from there -See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate types. +See [REFERENCE.md](../../../skills/orchestrate-project/REFERENCE.md) for detailed phase specifications and gate types. ## How Orchestrate Works @@ -58,7 +58,7 @@ See [REFERENCE.md](REFERENCE.md) for detailed phase specifications and gate type - **Fast-Track**: Skip negotiable gates. Use for hotfixes and minor improvements. - **Ad-Hoc**: Warnings only. Use for prototyping and spikes (non-production). -See [REFERENCE.md](REFERENCE.md) for full mode behaviors. +See [REFERENCE.md](../../../skills/orchestrate-project/REFERENCE.md) for full mode behaviors. ## Verification diff --git a/.pi/skills/organize-workspace/SKILL.md b/.pi/skills/organize-workspace/SKILL.md index 01dba5d0..cd9578f0 100644 --- a/.pi/skills/organize-workspace/SKILL.md +++ b/.pi/skills/organize-workspace/SKILL.md @@ -74,7 +74,7 @@ Do this when the repo is under Git and the cleanup surfaced **untracked** noise: 4. **User must approve** the exact diff before editing the file. 5. **Verify**: run `git check-ignore -v ` on 2–3 representative paths. -See [REFERENCE.md](REFERENCE.md) for shell patterns, `.gitignore` mechanics, and safety checks. +See [REFERENCE.md](../../../skills/organize-workspace/REFERENCE.md) for shell patterns, `.gitignore` mechanics, and safety checks. diff --git a/.pi/skills/plan-refactor/SKILL.md b/.pi/skills/plan-refactor/SKILL.md index 823919d9..149cb9f4 100644 --- a/.pi/skills/plan-refactor/SKILL.md +++ b/.pi/skills/plan-refactor/SKILL.md @@ -81,7 +81,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/.pi/skills/plan-release/SKILL.md b/.pi/skills/plan-release/SKILL.md index 631068f9..75b2ac1b 100644 --- a/.pi/skills/plan-release/SKILL.md +++ b/.pi/skills/plan-release/SKILL.md @@ -17,7 +17,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -102,7 +102,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/.pi/skills/plan-work/SKILL.md b/.pi/skills/plan-work/SKILL.md index 355455ca..d2886e46 100644 --- a/.pi/skills/plan-work/SKILL.md +++ b/.pi/skills/plan-work/SKILL.md @@ -45,7 +45,7 @@ If this plan touches an existing module, run `assess-impact` first to understand 2. **Draft steps** — Break implementation into the smallest possible steps where each step leaves the codebase working, has one observable outcome, and can be verified with a single command. Red-flag check: name any rationalization you caught before moving to step 3. -3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. Each task should also include an `allure:` block to drive test reporting: `severity:` maps risk to Allure severity (`P0→critical`, `P1→high`, `P2→normal`, `P3→minor`), and `categories:` is a list of relevant tags like `"Security Review"`, wave names, or test categories (see REFERENCE.md for the full template). +3. **Write capsule story spec + tasks** — Output two files inside the active epic capsule. See [REFERENCE.md](../../../skills/plan-work/REFERENCE.md) for file formats and the plan-template. Each task MUST include a `risk:` field (`P0` | `P1` | `P2` | `P3`) based on BCP + story type heuristics (see REFERENCE.md). If a test plan artifact (`specs/tech-architecture/eNN-TEST_PLAN_LATEST.md`) exists, read it and inherit its P0/P1 risk classifications and scenario IDs (`SC-eNNsYY-P0-NN`). Each task optionally includes a `security:` field (`none` / `low` / `medium` / `high`) sourced from the epic's `specs/security/epics//THREAT_MODEL.md`. Tasks with `security: medium` or `security: high` MUST include "no new security findings in affected paths" in their verify steps. Each task should also include an `allure:` block to drive test reporting: `severity:` maps risk to Allure severity (`P0→critical`, `P1→high`, `P2→normal`, `P3→minor`), and `categories:` is a list of relevant tags like `"Security Review"`, wave names, or test categories (see REFERENCE.md for the full template). **Requirement delta tags (e45s29):** When a story modifies existing behavior, the story spec § Requirements MUST use OpenSpec-style delta tags with mandatory before/after content: @@ -58,7 +58,7 @@ If this plan touches an existing module, run `assess-impact` first to understand Net-new stories (greenfield) use `ADDED` only. `MODIFIED`/`REMOVED`/`RENAMED` without before/after blocks fail the plan-work gate. -4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](REFERENCE.md) for good/bad examples. +4. **Verify step format** — Every step MUST follow: `N. → verify: `. See [REFERENCE.md](../../../skills/plan-work/REFERENCE.md) for good/bad examples. 4a. **Cross-artifact consistency pass (HARD GATE — e45s04)** — Before handoff, run: diff --git a/.pi/skills/publish-package/SKILL.md b/.pi/skills/publish-package/SKILL.md index c2a75da7..dceae9c0 100644 --- a/.pi/skills/publish-package/SKILL.md +++ b/.pi/skills/publish-package/SKILL.md @@ -33,41 +33,41 @@ If no manifest is found, prompt the user to specify the type or pass `--type **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](REFERENCE.md#three-independent-facts-release). +> **HARD GATE** — Do NOT declare success until CI completes. **Three-independent-facts** (e45s15): commit landed, workflow green, registry visible — see [REFERENCE.md](../../../skills/release-branch/REFERENCE.md#three-independent-facts-release). ```bash bash scripts/wait-for-ci.sh --timeout 600 --interval 30 @@ -131,7 +131,7 @@ bash scripts/wait-for-ci.sh --timeout 600 --interval 30 ### 8. Clean up & return -Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](REFERENCE.md#cycle-time). +Worktree prune, branch delete, `git checkout main`. Cycle-time: see [REFERENCE.md](../../../skills/release-branch/REFERENCE.md#cycle-time). Report: "Branch released." diff --git a/.pi/skills/research-first/SKILL.md b/.pi/skills/research-first/SKILL.md index ac513104..5b74005c 100644 --- a/.pi/skills/research-first/SKILL.md +++ b/.pi/skills/research-first/SKILL.md @@ -52,7 +52,7 @@ If opensrc is not installed or the package is not cached, fall through to web do → verify: `grep -c "Prior Art" specs/product/SCOPE_LATEST.yaml specs/release-plan.yaml + epic shards 2>/dev/null | awk '{s+=$1} END {if(s>0) print "OK"; else print "MISSING"}'` -See [REFERENCE.md](REFERENCE.md) for search commands and registry checklist. +See [REFERENCE.md](../../../skills/research-first/REFERENCE.md) for search commands and registry checklist. --- diff --git a/.pi/skills/run-evals/SKILL.md b/.pi/skills/run-evals/SKILL.md index 9ac8aaef..3bcdb980 100644 --- a/.pi/skills/run-evals/SKILL.md +++ b/.pi/skills/run-evals/SKILL.md @@ -30,7 +30,7 @@ description: "Eval-Driven Development — define capability and regression evals ## Artefact -`specs/verifications/eNNsYY-eval-report.md` — see [REFERENCE.md](REFERENCE.md) for template. Eval reports are stored alongside verification evidence in `specs/verifications/`, keyed by story ID for traceability. +`specs/verifications/eNNsYY-eval-report.md` — see [REFERENCE.md](../../../skills/run-evals/REFERENCE.md) for template. Eval reports are stored alongside verification evidence in `specs/verifications/`, keyed by story ID for traceability. ## Verify diff --git a/.pi/skills/security-review/SKILL.md b/.pi/skills/security-review/SKILL.md index aaa007d8..0b5952d8 100644 --- a/.pi/skills/security-review/SKILL.md +++ b/.pi/skills/security-review/SKILL.md @@ -103,9 +103,9 @@ Each finding: **`File:Line` — Severity — Category** ## Reference files -- [Vuln categories](REFERENCE-vuln-categories.md) — detection guidance per vuln type -- [False positives](REFERENCE-false-positives.md) — hard exclusions + precedent -- [Confidence rubric](REFERENCE-confidence-rubric.md) — scoring methodology (0–10) +- [Vuln categories](../../../skills/security-review/REFERENCE-vuln-categories.md) — detection guidance per vuln type +- [False positives](../../../skills/security-review/REFERENCE-false-positives.md) — hard exclusions + precedent +- [Confidence rubric](../../../skills/security-review/REFERENCE-confidence-rubric.md) — scoring methodology (0–10) ## Verify diff --git a/.pi/skills/seed-conventions/SKILL.md b/.pi/skills/seed-conventions/SKILL.md index 483e784c..cac9802b 100644 --- a/.pi/skills/seed-conventions/SKILL.md +++ b/.pi/skills/seed-conventions/SKILL.md @@ -37,11 +37,11 @@ Ask the user these questions (one at a time, wait for each answer): 5. **Conventions** — "Any naming, file organization, or patterns all agents must follow?" 6. **Never-do list** — "What are the hard stops? Things an agent must never touch?" 7. **Defensive code categories** — "Which apply? (Rate limit / Retry / Circuit breaker / Timeout / Graceful degradation)" -8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in). +8. **Local tool wiring (optional)** — "Wire bigpowers for project-local tools? (Cursor, OpenCode, Cline, Aider, Codex CLI)" If yes, generate AGENTS.md spine artifacts per [REFERENCE.md](../../../skills/seed-conventions/REFERENCE.md) §Local tool wiring and §AGENTS.md spine. If no, skip — standard seed output unchanged (no AGENTS.md spine unless opted in). ## Generate files -After the interview, generate each file using the templates in [REFERENCE.md](REFERENCE.md): +After the interview, generate each file using the templates in [REFERENCE.md](../../../skills/seed-conventions/REFERENCE.md): - `AGENTS.md` — from `docs/templates/AGENTS.md` Reach Template (canonical spine source) - `CLAUDE.md` — symlink to `AGENTS.md` (copy fallback on Windows when symlink fails) - `GEMINI.md` — symlink to `AGENTS.md` when Gemini wiring opted in @@ -81,7 +81,7 @@ Skills that write into `CLAUDE.md` or `AGENTS.md` MUST use **fenced HTML comment **Merge rule:** On update, replace only the content *between* matching `BEGIN`/`END` pairs. If a marker pair is missing, append a new fenced block at the end of the file — never rewrite the whole file. -**Standard marker IDs** for seeded projects (see [REFERENCE.md](REFERENCE.md) § Fenced markers): +**Standard marker IDs** for seeded projects (see [REFERENCE.md](../../../skills/seed-conventions/REFERENCE.md) § Fenced markers): | Marker ID | Owner skill | Purpose | |-----------|-------------|---------| diff --git a/.pi/skills/smoke-test/SKILL.md b/.pi/skills/smoke-test/SKILL.md index c9f416c1..b5dfa1d5 100644 --- a/.pi/skills/smoke-test/SKILL.md +++ b/.pi/skills/smoke-test/SKILL.md @@ -21,7 +21,7 @@ Can be run standalone for quick health checks or chained as the final step of th Smoke checks are defined in `smoke-checks.yaml` at the project root: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/smoke-test/REFERENCE.md) Checks can also be specified inline via environment variables or CLI arguments for ad-hoc use. @@ -40,21 +40,21 @@ Checks can also be specified inline via environment variables or CLI arguments f ### 1. Load smoke checks -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/smoke-test/REFERENCE.md) ### 2. Run each check For each check in the configuration, perform an HTTP request: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/smoke-test/REFERENCE.md) ### 3. Assert results -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/smoke-test/REFERENCE.md) ### 4. Generate report -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/smoke-test/REFERENCE.md) ## Integration with deploy skill diff --git a/.pi/skills/stocktake-skills/SKILL.md b/.pi/skills/stocktake-skills/SKILL.md index 34ff4e97..b03cb0af 100644 --- a/.pi/skills/stocktake-skills/SKILL.md +++ b/.pi/skills/stocktake-skills/SKILL.md @@ -58,7 +58,7 @@ Timing data is populated by `scripts/bp-timing.sh start|end ` calls withi → verify: `test -f specs/STOCKTAKE-*.md && bash scripts/validate-skill-catalog.sh && echo OK || echo MISSING` -See [REFERENCE.md](REFERENCE.md) for checklist. +See [REFERENCE.md](../../../skills/stocktake-skills/REFERENCE.md) for checklist. --- diff --git a/.pi/skills/using-bigpowers/SKILL.md b/.pi/skills/using-bigpowers/SKILL.md index 8ef411d1..a3bf2f2c 100644 --- a/.pi/skills/using-bigpowers/SKILL.md +++ b/.pi/skills/using-bigpowers/SKILL.md @@ -77,7 +77,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/.pi/skills/validate-contracts/SKILL.md b/.pi/skills/validate-contracts/SKILL.md index 53fa3ea7..89ff8a49 100644 --- a/.pi/skills/validate-contracts/SKILL.md +++ b/.pi/skills/validate-contracts/SKILL.md @@ -28,13 +28,13 @@ Three modes of validation: All contract files live in `specs/contracts/` and use YAML: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. ### 1. API Response Contracts (`--schema`) Define expected API response shapes and validate live endpoints against them: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. Usage: @@ -48,21 +48,21 @@ validate-contracts --schema specs/contracts/users.schema.yaml --url https://api. Assert that two data sources share a consistent set of keys: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. Usage: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. ### 3. Data Shape Contracts (`--shape`) Validate that a data file matches expected column types and constraints: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. Usage: -See [REFERENCE.md](REFERENCE.md) for examples. +See [REFERENCE.md](../../../skills/validate-contracts/REFERENCE.md) for examples. ## Process diff --git a/.pi/skills/verify-work/SKILL.md b/.pi/skills/verify-work/SKILL.md index f35790be..b16577ac 100644 --- a/.pi/skills/verify-work/SKILL.md +++ b/.pi/skills/verify-work/SKILL.md @@ -137,7 +137,7 @@ for p in specs/conventions-wiki/*.md; do [ "$(basename "$p")" = "index.md" ]&&co ## --cli mode -CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode). +CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](../../../skills/verify-work/REFERENCE.md#cli-mode). ## Verify diff --git a/.pi/skills/wire-ci/SKILL.md b/.pi/skills/wire-ci/SKILL.md index 8eb25c4b..f22fc5a8 100644 --- a/.pi/skills/wire-ci/SKILL.md +++ b/.pi/skills/wire-ci/SKILL.md @@ -42,25 +42,25 @@ If no manifest is found, prompt the user to specify the type or pass `--type **NPM_TOKEN is required** for publishing to npm. Without it, semantic-release will fail at the publish step. See `--validate` to check this. @@ -68,7 +68,7 @@ See [REFERENCE.md](REFERENCE.md) Run `wire-ci --validate` to check all generated workflow files: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md) **Exit codes:** - `0` — all checks pass (no errors) @@ -79,7 +79,7 @@ See [REFERENCE.md](REFERENCE.md) Attempt to run the generated workflows locally to catch errors before push: -See [REFERENCE.md](REFERENCE.md) +See [REFERENCE.md](../../../skills/wire-ci/REFERENCE.md) > **act** runs workflows in a local Docker environment — the most accurate pre-push validation. > **gh workflow run** sends the workflow to GitHub but doesn't execute locally — useful for checking YAML parsing but not for testing the actual steps. diff --git a/.pi/skills/write-document/SKILL.md b/.pi/skills/write-document/SKILL.md index 3b4baf59..b49ff071 100644 --- a/.pi/skills/write-document/SKILL.md +++ b/.pi/skills/write-document/SKILL.md @@ -46,7 +46,7 @@ Write the document focusing on "Expert Collaboration": ### Quick README (Project READMEs only) 1. Ask: "Project name? One-sentence description?" -2. Generate `README.md` at project root using the template in [REFERENCE.md](REFERENCE.md) — no TOC, no second interview round. +2. Generate `README.md` at project root using the template in [REFERENCE.md](../../../skills/write-document/REFERENCE.md) — no TOC, no second interview round. 3. Fill gaps from `CLAUDE.md` commands if available; use `TODO` markers otherwise. 4. Output and suggest `edit-document` for polish. @@ -220,7 +220,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -237,7 +237,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/docs/references/model-profiles.md b/docs/references/model-profiles.md index 049279be..b9ac5a04 100644 --- a/docs/references/model-profiles.md +++ b/docs/references/model-profiles.md @@ -239,85 +239,85 @@ Start: Task assigned | Skill | Model | |-------|-------| -| `/Users/danielvm/Developer/bigpowers/skills/align-grid` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/assess-impact` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/audit-code` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/audit-plan` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/build-epic` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/change-request` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/commit-message` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/compose-workflow` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/context7-mcp` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/craft-skill` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/deepen-architecture` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/define-language` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/define-success` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/delegate-task` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/deploy` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/design-interface` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/develop-tdd` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/diagnose-root` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/diagnose-stall` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/dispatch-agents` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/edit-document` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/elaborate-spec` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/enforce-first` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/evolve-skill` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/execute-plan` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/extract-design` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/fix-bug` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/gate-trace` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/generate-allure-report` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/grill-me` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/grill-with-docs` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/guard-git` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/harden-vps` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/hook-commits` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/inspect-quality` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/investigate-bug` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/kickoff-branch` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/maintain-wiki` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/map-codebase` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/migrate-spec` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/model-domain` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/orchestrate-project` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/organize-workspace` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/plan-refactor` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/plan-release` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/plan-tests` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/plan-work` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/publish-package` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/quick-fix` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/release-branch` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/request-review` | **Opus** | -| `/Users/danielvm/Developer/bigpowers/skills/research-first` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/reset-baseline` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/respond-review` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/run-benchmark` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/run-evals` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/run-planning` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/scope-work` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/search-skills` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/security-review` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/seed-conventions` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/session-state` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/setup-environment` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/simulate-agents` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/slice-tasks` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/smoke-test` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/spike-prototype` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/stocktake-skills` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/survey-context` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/terse-mode` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/trace-requirement` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/using-bigpowers` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/validate-contracts` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/validate-fix` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/verify-work` | **Haiku** | -| `/Users/danielvm/Developer/bigpowers/skills/visual-dashboard` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/wire-ci` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/wire-observability` | **Sonnet** | -| `/Users/danielvm/Developer/bigpowers/skills/write-document` | **Sonnet** | +| `skills/align-grid` | **Sonnet** | +| `skills/assess-impact` | **Sonnet** | +| `skills/audit-code` | **Haiku** | +| `skills/audit-plan` | **Sonnet** | +| `skills/build-epic` | **Sonnet** | +| `skills/change-request` | **Sonnet** | +| `skills/commit-message` | **Haiku** | +| `skills/compose-workflow` | **Sonnet** | +| `skills/context7-mcp` | **Haiku** | +| `skills/craft-skill` | **Sonnet** | +| `skills/deepen-architecture` | **Sonnet** | +| `skills/define-language` | **Sonnet** | +| `skills/define-success` | **Sonnet** | +| `skills/delegate-task` | **Sonnet** | +| `skills/deploy` | **Sonnet** | +| `skills/design-interface` | **Opus** | +| `skills/develop-tdd` | **Sonnet** | +| `skills/diagnose-root` | **Sonnet** | +| `skills/diagnose-stall` | **Haiku** | +| `skills/dispatch-agents` | **Sonnet** | +| `skills/edit-document` | **Sonnet** | +| `skills/elaborate-spec` | **Opus** | +| `skills/enforce-first` | **Haiku** | +| `skills/evolve-skill` | **Opus** | +| `skills/execute-plan` | **Haiku** | +| `skills/extract-design` | **Sonnet** | +| `skills/fix-bug` | **Sonnet** | +| `skills/gate-trace` | **Haiku** | +| `skills/generate-allure-report` | **Sonnet** | +| `skills/grill-me` | **Sonnet** | +| `skills/grill-with-docs` | **Opus** | +| `skills/guard-git` | **Haiku** | +| `skills/harden-vps` | **Haiku** | +| `skills/hook-commits` | **Haiku** | +| `skills/inspect-quality` | **Sonnet** | +| `skills/investigate-bug` | **Sonnet** | +| `skills/kickoff-branch` | **Haiku** | +| `skills/maintain-wiki` | **Haiku** | +| `skills/map-codebase` | **Sonnet** | +| `skills/migrate-spec` | **Sonnet** | +| `skills/model-domain` | **Sonnet** | +| `skills/orchestrate-project` | **Sonnet** | +| `skills/organize-workspace` | **Haiku** | +| `skills/plan-refactor` | **Sonnet** | +| `skills/plan-release` | **Sonnet** | +| `skills/plan-tests` | **Opus** | +| `skills/plan-work` | **Opus** | +| `skills/publish-package` | **Sonnet** | +| `skills/quick-fix` | **Sonnet** | +| `skills/release-branch` | **Haiku** | +| `skills/request-review` | **Opus** | +| `skills/research-first` | **Sonnet** | +| `skills/reset-baseline` | **Haiku** | +| `skills/respond-review` | **Sonnet** | +| `skills/run-benchmark` | **Haiku** | +| `skills/run-evals` | **Sonnet** | +| `skills/run-planning` | **Sonnet** | +| `skills/scope-work` | **Sonnet** | +| `skills/search-skills` | **Haiku** | +| `skills/security-review` | **Sonnet** | +| `skills/seed-conventions` | **Sonnet** | +| `skills/session-state` | **Haiku** | +| `skills/setup-environment` | **Haiku** | +| `skills/simulate-agents` | **Sonnet** | +| `skills/slice-tasks` | **Sonnet** | +| `skills/smoke-test` | **Sonnet** | +| `skills/spike-prototype` | **Sonnet** | +| `skills/stocktake-skills` | **Sonnet** | +| `skills/survey-context` | **Haiku** | +| `skills/terse-mode` | **Haiku** | +| `skills/trace-requirement` | **Haiku** | +| `skills/using-bigpowers` | **Sonnet** | +| `skills/validate-contracts` | **Sonnet** | +| `skills/validate-fix` | **Haiku** | +| `skills/verify-work` | **Haiku** | +| `skills/visual-dashboard` | **Sonnet** | +| `skills/wire-ci` | **Sonnet** | +| `skills/wire-observability` | **Sonnet** | +| `skills/write-document` | **Sonnet** | Total: **79** skills — verify with `find . skills -maxdepth 2 -name SKILL.md 2>/dev/null | grep -v '.git\|.cursor\|.gemini\|.pi' | sort -u | wc -l` diff --git a/package.json b/package.json index a1e6e649..b372b02c 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers", "main": "index.js", "scripts": { - "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh", + "compliance": "bash scripts/audit-compliance.sh specs/verifications/features && bash scripts/validate-doctrine.sh && python3 scripts/check-skill-links.py", "doctrine": "bash scripts/validate-doctrine.sh", "sync": "bash scripts/sync-skills.sh", "validate-specs": "bash scripts/validate-specs-yaml.sh", @@ -15,7 +15,8 @@ "dashboard:web": "node dashboard/bin/dashboard.js --web", "site:dev": "cd website && npm run dev", "site:build": "cd website && npm run build", - "site:preview": "cd website && npm run preview" + "site:preview": "cd website && npm run preview", + "check:skill-links": "python3 scripts/check-skill-links.py" }, "keywords": [ "skills", diff --git a/scripts/adapters/pi.sh b/scripts/adapters/pi.sh index e5ce5ab6..8c024f4a 100755 --- a/scripts/adapters/pi.sh +++ b/scripts/adapters/pi.sh @@ -17,7 +17,7 @@ render_skill() { echo "description: \"$IR_DESC_ESCAPED\"" echo "---" echo "" - echo "$IR_BODY" + echo "${IR_BODY_SKILL:-$IR_BODY}" } > "${PI_SKILLS}/$IR_NAME/SKILL.md" } @@ -45,6 +45,9 @@ if [[ ! -t 0 ]]; then IR_MODEL=$(echo "$JSON_INPUT" | jq -r '.model') IR_DESCRIPTION=$(echo "$JSON_INPUT" | jq -r '.description') IR_BODY=$(echo "$JSON_INPUT" | jq -r '.body') + # Skill files get link-rewritten bodies (relative links repointed from + # .pi/skills// to the shipped source tree); prompts keep the raw body. + IR_BODY_SKILL=$(echo "$JSON_INPUT" | jq -r '.body_pi_skill // .body') IR_DESC_ESCAPED=$(echo "$IR_DESCRIPTION" | sed 's/\\/\\\\/g; s/\"/\\"/g') render_skill fi diff --git a/scripts/check-skill-links.py b/scripts/check-skill-links.py new file mode 100644 index 00000000..45ea59e4 --- /dev/null +++ b/scripts/check-skill-links.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +# check-skill-links.py — fail on machine-absolute paths or dangling relative +# links in skill docs. Scans skills/**/SKILL.md and .pi/skills/**/SKILL.md. +# Run: python3 scripts/check-skill-links.py (exit 1 with a report on failure) +# +# NOTE: .cursor/rules/ and .gemini/extensions/ are intentionally excluded. +# Those trees are auto-generated from SKILL.md sources via sync-skills.sh and +# are not published to npm, so dangling links there are a rendering gap, not a +# source defect. Enable once the sync pipeline gains link-rewriting support. +# See: https://github.com/danielvm-git/bigpowers/issues/78 +import glob +import os +import sys + +# Import shared patterns — single source of truth so the rewriter (srp-engine) +# and the gate always agree on what constitutes a "link". +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +from lib.link_utils import LINK_RE, EXTERNAL_RE, MACHINE_PATH_RE, strip_code_spans # noqa: E402 + + +def resolve_repo_root() -> str: + here = os.path.dirname(os.path.abspath(__file__)) + candidate = os.path.dirname(here) # scripts/ -> repo root + if os.path.isdir(os.path.join(candidate, "skills")): + return candidate + return os.getcwd() + + +def check_file_links(smd: str, root: str) -> list[str]: + """Return a list of problem strings for a single SKILL.md file.""" + rel = os.path.relpath(smd, root) + with open(smd, encoding="utf-8") as f: + text = f.read() + + problems = [] + + # Machine-absolute path check runs on raw text (line-by-line for location). + for i, line in enumerate(text.splitlines(), 1): + if MACHINE_PATH_RE.search(line): + problems.append(f"{rel}:{i}: machine-absolute path: {line.strip()[:100]}") + + # Link check runs on shadow (code spans blanked) to avoid false positives + # on example paths shown inside fenced blocks or inline code. + shadow = strip_code_spans(text) + for m in LINK_RE.finditer(shadow): + target = m.group(2).split("#", 1)[0] # strip fragment + if not target or EXTERNAL_RE.match(target) or target.startswith(("#", "/")): + continue + resolved = os.path.normpath(os.path.join(os.path.dirname(smd), target)) + if not os.path.exists(resolved): + problems.append(f"{rel}: dangling link -> {target}") + + return problems + + +def check(root: str) -> list[str]: + problems = [] + for tree in ("skills", os.path.join(".pi", "skills")): + pattern = os.path.join(root, tree, "*", "SKILL.md") + for smd in sorted(glob.glob(pattern)): + problems.extend(check_file_links(smd, root)) + return problems + + +def main() -> int: + root = resolve_repo_root() + problems = check(root) + if problems: + print(f"check-skill-links: {len(problems)} problem(s):") + for p in problems: + print(f" {p}") + return 1 + print("check-skill-links: OK — no machine paths or dangling links") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/scripts/generate-reference-tables.sh b/scripts/generate-reference-tables.sh index 4eb5740b..30b38fe8 100755 --- a/scripts/generate-reference-tables.sh +++ b/scripts/generate-reference-tables.sh @@ -32,10 +32,11 @@ BLOCK=" -- [Feathers' Seams & Characterization Tests](../../docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm -- [Fowler's Code Smells](../../docs/references/fowler.md) — identifying structural problems by smell before investigating +- [Feathers' Seams & Characterization Tests](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/feathers.md) — seam types, characterization tests, and the legacy code change algorithm +- [Fowler's Code Smells](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — identifying structural problems by smell before investigating diff --git a/skills/model-domain/CONTEXT-FORMAT.md b/skills/model-domain/CONTEXT-FORMAT.md index 493859ec..41802034 100644 --- a/skills/model-domain/CONTEXT-FORMAT.md +++ b/skills/model-domain/CONTEXT-FORMAT.md @@ -57,9 +57,9 @@ _Avoid_: Client, buyer, account ## Contexts -- [Ordering](./src/ordering/CONTEXT.md) — receives and tracks customer orders -- [Billing](./src/billing/CONTEXT.md) — generates invoices and processes payments -- [Fulfillment](./src/fulfillment/CONTEXT.md) — manages warehouse picking and shipping +- Ordering — `src/ordering/CONTEXT.md` — receives and tracks customer orders +- Billing — `src/billing/CONTEXT.md` — generates invoices and processes payments +- Fulfillment — `src/fulfillment/CONTEXT.md` — manages warehouse picking and shipping ## Relationships diff --git a/skills/plan-refactor/SKILL.md b/skills/plan-refactor/SKILL.md index e8a831bd..13f24c5e 100644 --- a/skills/plan-refactor/SKILL.md +++ b/skills/plan-refactor/SKILL.md @@ -82,8 +82,8 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next -- [Fowler's Refactoring Catalog](../../docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy -- [Beck's Tidy First?](../../docs/references/kent-beck.md) — structural change before behavioral change +- [Fowler's Refactoring Catalog](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/fowler.md) — canonical refactoring vocabulary and code-smell taxonomy +- [Beck's Tidy First?](https://github.com/danielvm-git/bigpowers/blob/main/docs/references/kent-beck.md) — structural change before behavioral change ## Verify diff --git a/skills/plan-release/SKILL.md b/skills/plan-release/SKILL.md index 0c394394..e4a28271 100644 --- a/skills/plan-release/SKILL.md +++ b/skills/plan-release/SKILL.md @@ -17,7 +17,7 @@ Synthesize the conversation context into `specs/release-plan.yaml` (index) and s |------|---------| | `specs/release-plan.yaml` | `release.version`, semver bump hint, WSJF-ordered epic list with `id`, `capsule_dir`, `wsjf`, `bcps` — **no story status** | | `specs/epics/eNN-/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list | -| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | +| `specs/epics/eNN-/eNNsYY-.md` | Story spec in [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md) with 20 sections and Gherkin acceptance criteria | | `specs/epics/eNN-/eNNsYY-tasks.yaml` | Decoupled task checklist with `verify:` commands per task | | `specs/execution-status.yaml` | Flat key-value store for story status (`eNNsYY: todo`) | @@ -102,7 +102,7 @@ stories: ``` ### 6. Save story specs (countable-story-format .md) -Each story becomes a standalone `.md` file following [countable-story-format.md](file:///Users/danielvm/Developer/bigpowers/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. +Each story becomes a standalone `.md` file following [countable-story-format.md](https://github.com/danielvm-git/bigpowers/blob/main/docs/countable-story-format.md). Minimum: maturity 3 (Countable) with all 20 sections present. Acceptance criteria in §17 use Gherkin scenarios. ### 7. Save decoupled task files (`-tasks.yaml`) Each story has a decoupled `-tasks.yaml` with implementation steps: diff --git a/skills/using-bigpowers/SKILL.md b/skills/using-bigpowers/SKILL.md index 4d709484..c6b83fc2 100644 --- a/skills/using-bigpowers/SKILL.md +++ b/skills/using-bigpowers/SKILL.md @@ -78,7 +78,7 @@ UTILITY terse-mode / craft-skill / edit-document (any phase) If you work alone and do not want PR ceremony every task: -1. Read [profiles/solo-git.md](../profiles/solo-git.md). +1. Read [profiles/solo-git.md](../../profiles/solo-git.md). 2. Register with `compose-workflow` → `specs/WORKFLOW-solo-git.md`. 3. Ship with `release-branch` in **solo-local** mode (`land-branch.sh`), not `gh pr create`. diff --git a/skills/write-document/REFERENCE.md b/skills/write-document/REFERENCE.md index 21750610..bb18a4e9 100644 --- a/skills/write-document/REFERENCE.md +++ b/skills/write-document/REFERENCE.md @@ -141,7 +141,7 @@ Auto-fill from CLAUDE.md `Test` and `Lint` commands. ```markdown ## Changelog -See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). +See [CHANGELOG.md](../../CHANGELOG.md) or [Releases](https://github.com/user/repo/releases). ``` ### 13. Links @@ -158,7 +158,7 @@ See [CHANGELOG.md](CHANGELOG.md) or [Releases](https://github.com/user/repo/rele ```markdown ## License -MIT — see [LICENSE](LICENSE) for details. +MIT — see [LICENSE](../../LICENSE) for details. ``` Detect from CLAUDE.md or project LICENSE file. diff --git a/tests/test_srp_engine.py b/tests/test_srp_engine.py new file mode 100644 index 00000000..85539589 --- /dev/null +++ b/tests/test_srp_engine.py @@ -0,0 +1,148 @@ +#!/usr/bin/env python3 +"""tests/test_srp_engine.py — unit tests for rewrite_links_for_pi and link_utils. + +Run: python3 -m pytest tests/test_srp_engine.py -v + or: python3 tests/test_srp_engine.py +""" +import os +import sys +import unittest + +# Make scripts/lib importable without installation. +_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__))) +_LIB = os.path.join(_REPO_ROOT, "scripts", "lib") +sys.path.insert(0, _LIB) +sys.path.insert(0, os.path.join(_REPO_ROOT, "scripts")) + +# srp-engine.py has a hyphen so we load it via importlib. +import importlib.util as _ilu +_spec = _ilu.spec_from_file_location("srp_engine", os.path.join(_LIB, "srp-engine.py")) +_srp = _ilu.module_from_spec(_spec) +sys.modules["srp_engine"] = _srp +_spec.loader.exec_module(_srp) + +from srp_engine import rewrite_links_for_pi # type: ignore[import] +from link_utils import strip_code_spans, LINK_RE, MACHINE_PATH_RE + + +class TestStripCodeSpans(unittest.TestCase): + def test_fenced_block_blanked(self): + md = "Before.\n```\n[fake](fake.md)\n```\nAfter." + shadow = strip_code_spans(md) + self.assertNotIn("[fake](fake.md)", shadow) + self.assertEqual(len(shadow), len(md)) # positions preserved + + def test_inline_code_blanked(self): + md = "Use `[x](y.md)` as an example." + shadow = strip_code_spans(md) + self.assertNotIn("[x](y.md)", shadow) + self.assertEqual(len(shadow), len(md)) + + def test_real_link_survives(self): + md = "See [docs](guide.md) for details." + shadow = strip_code_spans(md) + self.assertIn("[docs](guide.md)", shadow) + + +class TestLinkRE(unittest.TestCase): + def test_plain_link(self): + m = LINK_RE.search("[text](target.md)") + self.assertIsNotNone(m) + self.assertEqual(m.group(2), "target.md") + + def test_link_with_title(self): + m = LINK_RE.search('[text](target.md "My Title")') + self.assertIsNotNone(m) + self.assertEqual(m.group(2), "target.md") + + def test_link_with_fragment(self): + m = LINK_RE.search("[text](doc.md#section)") + self.assertIsNotNone(m) + self.assertEqual(m.group(2), "doc.md#section") + + def test_no_match_on_image(self): + # Image links (![...](url)) contain the same syntax — LINK_RE will match + # the inner part; they should be treated as pass-through by callers. + m = LINK_RE.search("![alt](image.png)") + # The regex matches the inner ](url) portion — callers must handle images. + self.assertIsNotNone(m) + + +class TestMachinePathRE(unittest.TestCase): + def test_file_uri(self): + self.assertTrue(MACHINE_PATH_RE.search("file:///Users/alice/project")) + + def test_macos_path(self): + self.assertTrue(MACHINE_PATH_RE.search("/Users/alice/project")) + + def test_linux_path(self): + self.assertTrue(MACHINE_PATH_RE.search("/home/alice/project")) + + def test_windows_path_single_backslash(self): + self.assertTrue(MACHINE_PATH_RE.search("C:\\Users\\alice")) + + def test_github_url_not_flagged(self): + self.assertFalse( + MACHINE_PATH_RE.search("https://github.com/danielvm-git/bigpowers") + ) + + +class TestRewriteLinksForPi(unittest.TestCase): + """Tests run without a real repo tree — path existence is irrelevant here; + we only verify that the URL construction logic is correct.""" + + NAME = "my-skill" + + def _rw(self, body): + return rewrite_links_for_pi(body, self.NAME) + + def test_external_link_untouched(self): + body = "[docs](https://example.com)" + self.assertEqual(self._rw(body), body) + + def test_anchor_only_untouched(self): + body = "[section](#heading)" + self.assertEqual(self._rw(body), body) + + def test_absolute_path_untouched(self): + body = "[root](/absolute/path.md)" + self.assertEqual(self._rw(body), body) + + def test_relative_link_repointed(self): + body = "[ref](REFERENCE.md)" + result = self._rw(body) + # Must not contain the original bare target + self.assertNotIn("](REFERENCE.md)", result) + # Must be a relative path targeting the skills source tree + self.assertIn("REFERENCE.md", result) + + def test_fragment_preserved(self): + body = "[section](REFERENCE.md#anchor)" + result = self._rw(body) + self.assertIn("#anchor", result) + # Fragment must not be mangled into a path component + self.assertNotIn("anchor" + os.sep, result) + + def test_link_with_title_attribute(self): + body = '[ref](REFERENCE.md "My Title")' + result = self._rw(body) + # Must not be left unrewritten + self.assertNotIn("](REFERENCE.md", result) + + def test_code_block_links_not_rewritten(self): + body = "Real: [ref](REFERENCE.md)\n\n```\n[fake](nowhere.md)\n```\n" + result = self._rw(body) + # The real link should be rewritten + self.assertNotIn("](REFERENCE.md)", result) + # The code-block link must be untouched + self.assertIn("[fake](nowhere.md)", result) + + def test_inline_code_link_not_rewritten(self): + body = "Example: `[x](bad.md)` — real [ref](REFERENCE.md)." + result = self._rw(body) + self.assertIn("[x](bad.md)", result) # inline code preserved + self.assertNotIn("](REFERENCE.md)", result) # real link rewritten + + +if __name__ == "__main__": + unittest.main()