bigpowers 2.77.0 → 2.77.2

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.77.0",
+  "version": "2.77.2",
   "description": "79 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/.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

package/.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.
 

package/.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)

package/.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.

package/.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.
 

package/.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).

package/.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
 
 <!-- story: e35s10 -->
 
-- [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

package/.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
 

package/.pi/prompts/plan-refactor.md

@@ -80,7 +80,7 @@ After writing `specs/REFACTOR_LATEST.md`, suggest running `kickoff-branch` next
 
 <!-- story: e35s10 -->
 
-- [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

package/.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-<slug>/epic.yaml` | Epic manifest: `id`, `title`, `wsjf`, `total_bcps`, `status`, `stories[]` list |
-| `specs/epics/eNN-<slug>/eNNsYY-<slug>.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-<slug>/eNNsYY-<slug>.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-<slug>/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:

package/.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`.
 

package/.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.

package/.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

package/.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.

package/.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.
 
 
 

package/.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.
 
 ---
 

package/.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
 

package/.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

package/.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
 

package/.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)
 

package/.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)

package/.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.
 
 
 <!-- story: e31s07 -->
@@ -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.

package/.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.
 
 ---
 

package/.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
 

package/.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.
 

package/.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.
 
 
 <!-- story: e03s01 -->

package/.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 <feature-branch>` 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).
 
 
 

package/.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
 

package/.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
 
 <!-- story: e35s10 -->
 
-- [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