From 8a847568676ebdd06224d45c6b5fed6542b8f64a Mon Sep 17 00:00:00 2001 From: korallis Date: Fri, 17 Jul 2026 13:26:41 +0100 Subject: [PATCH] fix(skills): repair machine-absolute and dangling relative links - replace file:///Users/danielvm countable-story-format links with the GitHub blob URL (docs/ is excluded from the npm package, so the file cannot be linked relatively in published installs) - evolve-skill: benchmark repo path is now machine-agnostic - craft-skill/investigate-bug/plan-refactor: docs/ links -> blob URLs - using-bigpowers: profiles link -> repo-relative; write-document: CHANGELOG/LICENSE -> repo-relative; guard-git: hooks/ -> REFERENCE.md (the bundle lives there); audit-code: drop dead REFERENCE.md link - grill-me/model-domain: de-link illustrative example paths - srp-engine: rewrite relative links for the pi tree so they resolve from .pi/skills// against the shipped source tree - pi adapter: render skill files from body_pi_skill (prompts unchanged) - add scripts/check-skill-links.py regression gate, wired into the compliance npm script Fixes #78 --- .cursor/rules/audit-code.mdc | 2 +- .cursor/rules/craft-skill.mdc | 4 +- .cursor/rules/elaborate-spec.mdc | 2 +- .cursor/rules/evolve-skill.mdc | 2 +- .cursor/rules/grill-me.mdc | 2 +- .cursor/rules/guard-git.mdc | 2 +- .cursor/rules/investigate-bug.mdc | 4 +- .cursor/rules/model-domain.mdc | 6 +- .cursor/rules/plan-refactor.mdc | 4 +- .cursor/rules/plan-release.mdc | 4 +- .cursor/rules/using-bigpowers.mdc | 2 +- .cursor/rules/write-document.mdc | 4 +- .../bigpowers/commands/prompts/audit-code.md | 2 +- .../bigpowers/commands/prompts/craft-skill.md | 4 +- .../commands/prompts/elaborate-spec.md | 2 +- .../commands/prompts/evolve-skill.md | 2 +- .../bigpowers/commands/prompts/grill-me.md | 2 +- .../bigpowers/commands/prompts/guard-git.md | 2 +- .../commands/prompts/investigate-bug.md | 4 +- .../commands/prompts/model-domain.md | 6 +- .../commands/prompts/plan-refactor.md | 4 +- .../commands/prompts/plan-release.md | 4 +- .../commands/prompts/using-bigpowers.md | 2 +- .../commands/prompts/write-document.md | 4 +- .../bigpowers/skills/audit-code/SKILL.md | 2 +- .../bigpowers/skills/craft-skill/SKILL.md | 4 +- .../bigpowers/skills/elaborate-spec/SKILL.md | 2 +- .../bigpowers/skills/evolve-skill/SKILL.md | 2 +- .../bigpowers/skills/grill-me/SKILL.md | 2 +- .../bigpowers/skills/guard-git/SKILL.md | 2 +- .../bigpowers/skills/investigate-bug/SKILL.md | 4 +- .../bigpowers/skills/model-domain/SKILL.md | 6 +- .../bigpowers/skills/plan-refactor/SKILL.md | 4 +- .../bigpowers/skills/plan-release/SKILL.md | 4 +- .../bigpowers/skills/using-bigpowers/SKILL.md | 2 +- .../bigpowers/skills/write-document/SKILL.md | 4 +- .pi/prompts/audit-code.md | 2 +- .pi/prompts/craft-skill.md | 4 +- .pi/prompts/elaborate-spec.md | 2 +- .pi/prompts/evolve-skill.md | 2 +- .pi/prompts/grill-me.md | 2 +- .pi/prompts/guard-git.md | 2 +- .pi/prompts/investigate-bug.md | 4 +- .pi/prompts/model-domain.md | 6 +- .pi/prompts/plan-refactor.md | 4 +- .pi/prompts/plan-release.md | 4 +- .pi/prompts/using-bigpowers.md | 2 +- .pi/prompts/write-document.md | 4 +- .pi/skills/audit-code/SKILL.md | 2 +- .pi/skills/change-request/SKILL.md | 2 +- .pi/skills/commit-message/SKILL.md | 6 +- .pi/skills/compose-workflow/SKILL.md | 2 +- .pi/skills/craft-skill/SKILL.md | 10 +- .pi/skills/deepen-architecture/SKILL.md | 26 +-- .pi/skills/deploy/SKILL.md | 8 +- .pi/skills/develop-tdd/SKILL.md | 10 +- .pi/skills/elaborate-spec/SKILL.md | 2 +- .pi/skills/evolve-skill/SKILL.md | 4 +- .pi/skills/extract-design/SKILL.md | 2 +- .pi/skills/generate-allure-report/SKILL.md | 2 +- .pi/skills/grill-me/SKILL.md | 4 +- .pi/skills/grill-with-docs/SKILL.md | 2 +- .pi/skills/guard-git/SKILL.md | 10 +- .pi/skills/harden-vps/SKILL.md | 2 +- .pi/skills/investigate-bug/SKILL.md | 4 +- .pi/skills/migrate-spec/SKILL.md | 26 +-- .pi/skills/model-domain/SKILL.md | 10 +- .pi/skills/orchestrate-project/SKILL.md | 4 +- .pi/skills/organize-workspace/SKILL.md | 2 +- .pi/skills/plan-refactor/SKILL.md | 4 +- .pi/skills/plan-release/SKILL.md | 4 +- .pi/skills/plan-work/SKILL.md | 4 +- .pi/skills/publish-package/SKILL.md | 16 +- .pi/skills/release-branch/SKILL.md | 4 +- .pi/skills/research-first/SKILL.md | 2 +- .pi/skills/run-evals/SKILL.md | 2 +- .pi/skills/security-review/SKILL.md | 6 +- .pi/skills/seed-conventions/SKILL.md | 6 +- .pi/skills/smoke-test/SKILL.md | 10 +- .pi/skills/stocktake-skills/SKILL.md | 2 +- .pi/skills/using-bigpowers/SKILL.md | 2 +- .pi/skills/validate-contracts/SKILL.md | 12 +- .pi/skills/verify-work/SKILL.md | 2 +- .pi/skills/wire-ci/SKILL.md | 16 +- .pi/skills/write-document/SKILL.md | 6 +- docs/references/model-profiles.md | 158 +++++++++--------- package.json | 5 +- scripts/adapters/pi.sh | 5 +- scripts/check-skill-links.py | 56 +++++++ scripts/lib/srp-engine.py | 38 ++++- skills-lock.json | 16 +- skills/audit-code/SKILL.md | 2 +- skills/craft-skill/SKILL.md | 4 +- skills/elaborate-spec/SKILL.md | 2 +- skills/evolve-skill/REFERENCE.md | 2 +- skills/grill-me/REFERENCE.md | 2 +- skills/guard-git/SKILL.md | 2 +- skills/investigate-bug/SKILL.md | 4 +- skills/model-domain/CONTEXT-FORMAT.md | 6 +- skills/plan-refactor/SKILL.md | 4 +- skills/plan-release/SKILL.md | 4 +- skills/using-bigpowers/SKILL.md | 2 +- skills/write-document/REFERENCE.md | 4 +- 103 files changed, 401 insertions(+), 305 deletions(-) create mode 100644 scripts/check-skill-links.py 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..f523d73b 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 @@ -135,7 +135,7 @@ description: Brief description of capability. Use when [specific triggers]. ## Advanced features -[Link to separate files: See [REFERENCE.md](REFERENCE.md)] +[Link to separate files: See [REFERENCE.md](../../../skills/craft-skill/REFERENCE.md)] ``` ## Description Requirements 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..d0bdfceb 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..41ec2b68 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** | +| `/tmp/bigpowers-pr/skills/align-grid` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/assess-impact` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/audit-code` | **Haiku** | +| `/tmp/bigpowers-pr/skills/audit-plan` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/build-epic` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/change-request` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/commit-message` | **Haiku** | +| `/tmp/bigpowers-pr/skills/compose-workflow` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/context7-mcp` | **Haiku** | +| `/tmp/bigpowers-pr/skills/craft-skill` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/deepen-architecture` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/define-language` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/define-success` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/delegate-task` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/deploy` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/design-interface` | **Opus** | +| `/tmp/bigpowers-pr/skills/develop-tdd` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/diagnose-root` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/diagnose-stall` | **Haiku** | +| `/tmp/bigpowers-pr/skills/dispatch-agents` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/edit-document` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/elaborate-spec` | **Opus** | +| `/tmp/bigpowers-pr/skills/enforce-first` | **Haiku** | +| `/tmp/bigpowers-pr/skills/evolve-skill` | **Opus** | +| `/tmp/bigpowers-pr/skills/execute-plan` | **Haiku** | +| `/tmp/bigpowers-pr/skills/extract-design` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/fix-bug` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/gate-trace` | **Haiku** | +| `/tmp/bigpowers-pr/skills/generate-allure-report` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/grill-me` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/grill-with-docs` | **Opus** | +| `/tmp/bigpowers-pr/skills/guard-git` | **Haiku** | +| `/tmp/bigpowers-pr/skills/harden-vps` | **Haiku** | +| `/tmp/bigpowers-pr/skills/hook-commits` | **Haiku** | +| `/tmp/bigpowers-pr/skills/inspect-quality` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/investigate-bug` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/kickoff-branch` | **Haiku** | +| `/tmp/bigpowers-pr/skills/maintain-wiki` | **Haiku** | +| `/tmp/bigpowers-pr/skills/map-codebase` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/migrate-spec` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/model-domain` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/orchestrate-project` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/organize-workspace` | **Haiku** | +| `/tmp/bigpowers-pr/skills/plan-refactor` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/plan-release` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/plan-tests` | **Opus** | +| `/tmp/bigpowers-pr/skills/plan-work` | **Opus** | +| `/tmp/bigpowers-pr/skills/publish-package` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/quick-fix` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/release-branch` | **Haiku** | +| `/tmp/bigpowers-pr/skills/request-review` | **Opus** | +| `/tmp/bigpowers-pr/skills/research-first` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/reset-baseline` | **Haiku** | +| `/tmp/bigpowers-pr/skills/respond-review` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/run-benchmark` | **Haiku** | +| `/tmp/bigpowers-pr/skills/run-evals` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/run-planning` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/scope-work` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/search-skills` | **Haiku** | +| `/tmp/bigpowers-pr/skills/security-review` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/seed-conventions` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/session-state` | **Haiku** | +| `/tmp/bigpowers-pr/skills/setup-environment` | **Haiku** | +| `/tmp/bigpowers-pr/skills/simulate-agents` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/slice-tasks` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/smoke-test` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/spike-prototype` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/stocktake-skills` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/survey-context` | **Haiku** | +| `/tmp/bigpowers-pr/skills/terse-mode` | **Haiku** | +| `/tmp/bigpowers-pr/skills/trace-requirement` | **Haiku** | +| `/tmp/bigpowers-pr/skills/using-bigpowers` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/validate-contracts` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/validate-fix` | **Haiku** | +| `/tmp/bigpowers-pr/skills/verify-work` | **Haiku** | +| `/tmp/bigpowers-pr/skills/visual-dashboard` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/wire-ci` | **Sonnet** | +| `/tmp/bigpowers-pr/skills/wire-observability` | **Sonnet** | +| `/tmp/bigpowers-pr/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..385dd7df --- /dev/null +++ b/scripts/check-skill-links.py @@ -0,0 +1,56 @@ +#!/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) +import glob +import os +import re +import sys + +MACHINE_PATH_RE = re.compile(r"file:///|/Users/|/home/|[A-Z]:\\\\Users") +LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)\s]+)\)") +EXTERNAL_RE = re.compile(r"(?i)^(https?|ftp|mailto):") + + +def resolve_repo_root(): + here = os.path.dirname(os.path.abspath(__file__)) + if os.path.isdir(os.path.join(os.path.dirname(here), "skills")): + return os.path.dirname(here) + return os.getcwd() + + +def check(root): + 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)): + rel = os.path.relpath(smd, root) + with open(smd, encoding="utf-8") as f: + text = f.read() + 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]}") + for m in LINK_RE.finditer(text): + 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 main(): + 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/lib/srp-engine.py b/scripts/lib/srp-engine.py index 375057f5..87d58608 100755 --- a/scripts/lib/srp-engine.py +++ b/scripts/lib/srp-engine.py @@ -1,12 +1,40 @@ #!/usr/bin/env python3 # story: e48s15 import os +import re import sys import json import glob import subprocess import yaml +LINK_RE = re.compile(r'\[([^\]]*)\]\(([^)\s]+)\)') +EXTERNAL_RE = re.compile(r'(?i)^(https?|ftp|file|mailto):') + +def rewrite_links_for_pi(body, name): + """Repoint relative links so they resolve from .pi/skills//. + + Sibling *.md content is inlined into the rendered SKILL.md body, but the + links to those files (and to repo-root docs) still point at paths relative + to the source dir, so they dangle in the rendered tree. Repoint them at + the shipped source tree (skills/, profiles/, repo-root files) so links + resolve in repo checkouts and npm installs alike. External, anchor, and + absolute links pass through untouched. + """ + out_dir = os.path.join(".pi", "skills", name) + + def repl(m): + text, target = m.group(1), m.group(2).strip() + if EXTERNAL_RE.match(target) or target.startswith(('#', '/')): + return m.group(0) + resolved = os.path.normpath(os.path.join("skills", name, target)) + if resolved.startswith(".."): + return m.group(0) # escapes repo root; leave untouched + new_target = os.path.relpath(resolved, out_dir).replace(os.sep, '/') + return f"[{text}]({new_target})" + + return LINK_RE.sub(repl, body) + def resolve_repo_root(): lib_dir = os.path.dirname(os.path.abspath(__file__)) # scripts/lib/srp-engine.py -> two levels up is REPO_ROOT @@ -210,7 +238,11 @@ def main(): continue for adapter in adapters: - dispatch_to_adapter(skill_data, adapter, repo_root) + data = skill_data + if adapter == "pi": + data = dict(skill_data) + data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name']) + dispatch_to_adapter(data, adapter, repo_root) if okf_mode: render_okf_concept(skill_data, okf_wiki_skills) @@ -235,6 +267,10 @@ def main(): skill_data = parse_skill(skill_md_path) + if target == "pi": + skill_data = dict(skill_data) + skill_data["body_pi_skill"] = rewrite_links_for_pi(skill_data['body'], skill_data['name']) + if dry_run or not target: print(json.dumps(skill_data, indent=2)) return diff --git a/skills-lock.json b/skills-lock.json index 0df0a38e..e646b3db 100644 --- a/skills-lock.json +++ b/skills-lock.json @@ -13,7 +13,7 @@ }, "audit-code": { "description": "Self-review checklist for the coding agent to run before dispatching a reviewer. Checks CONVENTIONS.md compliance, Boy Scout Rule, test coverage, types, and SOLID. Produces a pass/fail checklist. Use before request-review, before committing, or when user asks for a code quality check.", - "sha256": "bbb128254464f8f4", + "sha256": "0636f1d9d6c591a3", "path": "skills/audit-codeSKILL.md" }, "audit-plan": { @@ -48,7 +48,7 @@ }, "craft-skill": { "description": "Create new bigpowers skills with proper structure, progressive disclosure, and bundled resources. Use when user wants to create, write, or build a new skill for the bigpowers lifecycle.", - "sha256": "cbf8ab939cfbab87", + "sha256": "2caa9d8ae9298b4b", "path": "skills/craft-skillSKILL.md" }, "deepen-architecture": { @@ -108,7 +108,7 @@ }, "elaborate-spec": { "description": "Refine a rough idea into a clear, detailed specification through dialogue. Does not produce code. Use when user has a vague idea, wants to think through a feature before planning, or needs to turn \"I want X\" into a concrete spec.", - "sha256": "62ebfca87e6d0162", + "sha256": "9307ab61c789a0a0", "path": "skills/elaborate-specSKILL.md" }, "enforce-first": { @@ -158,7 +158,7 @@ }, "guard-git": { "description": "Block dangerous git commands (push, force push, reset --hard, clean, branch -D, checkout/restore .) and enforce Conventional Commits & Branch Protection before an AI agent runs them. Installs hook scripts for Claude Code, Cursor, Cursor CLI, and Gemini CLI; documents Google Antigravity Terminal deny lists. Use when the user wants git safety hooks, to block git push or destructive git in agents, or to mirror the same policy across AI coding tools.", - "sha256": "9ee881df89273b00", + "sha256": "e7083cba6d95a15f", "path": "skills/guard-gitSKILL.md" }, "harden-vps": { @@ -178,7 +178,7 @@ }, "investigate-bug": { "description": "Investigate a bug or issue by exploring the codebase to find root cause, then write a TDD-based fix plan to specs/bugs/BUG-*.md. Use when user reports a bug, wants to investigate a problem, mentions \"triage\", or wants to plan a fix.", - "sha256": "b842fd329d1f7741", + "sha256": "54f8c5417be34ef0", "path": "skills/investigate-bugSKILL.md" }, "kickoff-branch": { @@ -218,12 +218,12 @@ }, "plan-refactor": { "description": "Create a detailed refactor plan with tiny commits via user interview, then save it as specs/REFACTOR_LATEST.md. Use when user wants to plan a refactor, create a refactoring RFC, or break a refactor into safe incremental steps.", - "sha256": "c418c850806e2f16", + "sha256": "2d18809da7cc9de8", "path": "skills/plan-refactorSKILL.md" }, "plan-release": { "description": "\"RELEASE-INDEX BUILDER — Sequence elaborated epics into specs/release-plan.yaml with WSJF ordering and BCP baselines. NOT a planning-spine substitute: it does not scope work (scope-work) or write story tasks (plan-work). Use after elaborate-spec when the user wants a versioned release index of epics.\"", - "sha256": "b56b800817cd383e", + "sha256": "9334ff48e5b1fab3", "path": "skills/plan-releaseSKILL.md" }, "plan-tests": { @@ -358,7 +358,7 @@ }, "using-bigpowers": { "description": "One-time bootstrap that introduces the bigpowers skills system, the PMBOK lifecycle arc, and tells you which skill to call first for your situation. Use when starting with bigpowers for the first time, when user asks \"where do I start?\", or when the skills system needs to be explained.", - "sha256": "332d6468868b759b", + "sha256": "bad9ebe9bf303b36", "path": "skills/using-bigpowersSKILL.md" }, "validate-contracts": { diff --git a/skills/audit-code/SKILL.md b/skills/audit-code/SKILL.md index 9c6b7842..dac596f6 100644 --- a/skills/audit-code/SKILL.md +++ b/skills/audit-code/SKILL.md @@ -31,7 +31,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/skills/craft-skill/SKILL.md b/skills/craft-skill/SKILL.md index 87e0c9e4..542902e1 100644 --- a/skills/craft-skill/SKILL.md +++ b/skills/craft-skill/SKILL.md @@ -33,7 +33,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? @@ -46,7 +46,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/skills/elaborate-spec/SKILL.md b/skills/elaborate-spec/SKILL.md index 33094b52..20e906e3 100644 --- a/skills/elaborate-spec/SKILL.md +++ b/skills/elaborate-spec/SKILL.md @@ -65,7 +65,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/skills/evolve-skill/REFERENCE.md b/skills/evolve-skill/REFERENCE.md index 40be4e73..6d72b296 100644 --- a/skills/evolve-skill/REFERENCE.md +++ b/skills/evolve-skill/REFERENCE.md @@ -9,4 +9,4 @@ **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/skills/grill-me/REFERENCE.md b/skills/grill-me/REFERENCE.md index 9e0c71d8..9c3f15ca 100644 --- a/skills/grill-me/REFERENCE.md +++ b/skills/grill-me/REFERENCE.md @@ -43,7 +43,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/skills/guard-git/SKILL.md b/skills/guard-git/SKILL.md index aa22e490..21cbfe3c 100644 --- a/skills/guard-git/SKILL.md +++ b/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/skills/investigate-bug/SKILL.md b/skills/investigate-bug/SKILL.md index 45af16d5..6f317ce7 100644 --- a/skills/investigate-bug/SKILL.md +++ b/skills/investigate-bug/SKILL.md @@ -124,6 +124,6 @@ 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/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.