From 036f1180000661143b289206e70e8835094593b6 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 11:02:44 +0200
Subject: [PATCH 01/10] refactor(skills): move cross-skill references into
 _shared
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

phase-execution.md, pattern-audit.md, and forge-scout.md were consumed by
forge-ship (and forge-scout by forge-implement) while living in
forge-implement's private directories — violating the self-containment
rule. Also drops the Refs # trailer convention stated nowhere else and
removes stale step/dimension references from pattern-audit.

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 CONTEXT.md                                               | 2 +-
 .../references => _shared}/pattern-audit.md              | 4 ++--
 .../references => _shared}/phase-execution.md            | 4 ++--
 skills/{forge-implement => _shared}/roles/forge-scout.md | 4 ++--
 skills/forge-implement/SKILL.md                          | 4 ++--
 skills/forge-ship/SKILL.md                               | 9 ++++++---
 6 files changed, 15 insertions(+), 12 deletions(-)
 rename skills/{forge-implement/references => _shared}/pattern-audit.md (89%)
 rename skills/{forge-implement/references => _shared}/phase-execution.md (94%)
 rename skills/{forge-implement => _shared}/roles/forge-scout.md (87%)

diff --git a/CONTEXT.md b/CONTEXT.md
index bf0d595..f1989c6 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -28,7 +28,7 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Smart zone / Dumb zone** — workable region (~first 100k tokens) vs degraded region of LLM context. See [architecture — Operating Constraints](docs/architecture.md#operating-constraints).
 
-**Pattern audit** — when a pattern changes, grep ALL files using the old pattern and update. See [pattern-audit](skills/forge-implement/references/pattern-audit.md).
+**Pattern audit** — when a pattern changes, grep ALL files using the old pattern and update. See [pattern-audit](skills/_shared/pattern-audit.md).
 
 **Quality gates** — lint, format, type check, tests. Run before commit, PR push, and reflection.
 
diff --git a/skills/forge-implement/references/pattern-audit.md b/skills/_shared/pattern-audit.md
similarity index 89%
rename from skills/forge-implement/references/pattern-audit.md
rename to skills/_shared/pattern-audit.md
index 5f15464..51b526f 100644
--- a/skills/forge-implement/references/pattern-audit.md
+++ b/skills/_shared/pattern-audit.md
@@ -13,8 +13,8 @@ When a pattern changes in a diff, find every other place using the old pattern a
 
 ## When to audit
 
-1. **During implementation** (Step 5) — the moment you change a pattern
-2. **During reflection** (Correctness & Patterns dimension) — catch what the implementer missed
+1. **During implementation** — the moment you change a pattern
+2. **During reflection** — the review pass checks pattern consistency to catch what the implementer missed
 
 ## Common failure modes
 
diff --git a/skills/forge-implement/references/phase-execution.md b/skills/_shared/phase-execution.md
similarity index 94%
rename from skills/forge-implement/references/phase-execution.md
rename to skills/_shared/phase-execution.md
index c16a878..a3d3dc5 100644
--- a/skills/forge-implement/references/phase-execution.md
+++ b/skills/_shared/phase-execution.md
@@ -30,7 +30,7 @@ Code and tests together, end to end across all affected layers.
 
 **Verify unfamiliar APIs before using them** — grep the codebase, check type definitions or docs, confirm the API exists at the project's pinned version. Skip for: stdlib, APIs already used in this codebase, type-checked interfaces.
 
-**Follow existing patterns and import style.** No barrel files unless the project uses them (see [barrel-imports](../../_shared/barrel-imports.md)).
+**Follow existing patterns and import style.** No barrel files unless the project uses them (see [barrel-imports](barrel-imports.md)).
 
 ### 2. Test
 
@@ -49,6 +49,6 @@ Verify before proceeding to the next phase:
 - [ ] Tests exist for new behavior in this phase
 - [ ] All tests pass (not just new ones)
 - [ ] No lint/type errors introduced
-- [ ] Commit the phase — one logical change per commit, conventional format, `Refs #<ISSUE_NUMBER>` when applicable
+- [ ] Commit the phase — one logical change per commit, conventional format
 
 Use TodoWrite to track progress through phases.
diff --git a/skills/forge-implement/roles/forge-scout.md b/skills/_shared/roles/forge-scout.md
similarity index 87%
rename from skills/forge-implement/roles/forge-scout.md
rename to skills/_shared/roles/forge-scout.md
index d224aa4..140b104 100644
--- a/skills/forge-implement/roles/forge-scout.md
+++ b/skills/_shared/roles/forge-scout.md
@@ -5,14 +5,14 @@ description: Researches a codebase to answer targeted questions without knowledg
 
 # Scout
 
-You are researching a codebase to answer specific questions. **You have no knowledge of what is being built or why.** You receive only questions — never the ticket, issue, or feature description.
+You are researching a codebase to answer specific questions. **You have no knowledge of what is being built or why.** You receive only questions — never the Issue, plan, or feature description.
 
 ## Behavior
 
 For each question:
 1. Search the codebase thoroughly — grep, glob, read files
 2. Trace relevant code paths end to end
-3. Report findings with file paths and function names
+3. Report answers with file paths and function names
 
 ## Rules
 
diff --git a/skills/forge-implement/SKILL.md b/skills/forge-implement/SKILL.md
index 50682a7..fe5a5c4 100644
--- a/skills/forge-implement/SKILL.md
+++ b/skills/forge-implement/SKILL.md
@@ -32,9 +32,9 @@ Identify **durable architectural decisions** — data model, API contracts, and
 
 #### Research (delegate)
 
-Write 3–7 factual questions about existing systems, patterns, and integration points. Delegate to a [forge-scout](roles/forge-scout.md) sub-agent that receives only the questions — not the issue. If no sub-agent support, read the role file and answer each question following its rules.
+Write 3–7 factual questions about existing systems, patterns, and integration points. Delegate to a [forge-scout](../_shared/roles/forge-scout.md) sub-agent that receives only the questions — not the Issue. If no sub-agent support, read the role file and answer each question following its rules.
 
-**Inputs:** Role: [forge-scout](roles/forge-scout.md), the research questions, codebase access.
+**Inputs provided to sub-agent:** Role: [forge-scout](../_shared/roles/forge-scout.md), the research questions, codebase access.
 **Expected output:** One factual answer per question, with file paths and code references.
 
 If the runtime supports per-task model choice, prefer a **cheap fast model** for scout work — scouting is factual reconnaissance, not deep synthesis. Otherwise inherit the parent session model and keep the scout task narrow.
diff --git a/skills/forge-ship/SKILL.md b/skills/forge-ship/SKILL.md
index 01b3d47..1a3271b 100644
--- a/skills/forge-ship/SKILL.md
+++ b/skills/forge-ship/SKILL.md
@@ -24,7 +24,10 @@ Determine input type (Issue number/URL, plan file, or free-text). For Issues, fe
 
 #### 1b. Plan
 
-For complex work, write 3–7 research questions and delegate to a sub-agent with the [forge-scout](../forge-implement/roles/forge-scout.md) role for unbiased codebase research. Prefer a cheap fast model for scout work.
+For complex work, write 3–7 research questions and delegate to a sub-agent with the [forge-scout](../_shared/roles/forge-scout.md) role for unbiased codebase research. Prefer a cheap fast model for scout work. If the runtime does not support sub-agents, read the role file and answer the questions inline following its rules.
+
+**Inputs provided to sub-agent:** Role: [forge-scout](../_shared/roles/forge-scout.md), the research questions, codebase access.
+**Expected output:** One factual answer per question, with file paths and code references.
 
 From the research, create a plan: durable decisions, vertical phases (see [vertical-slicing](../_shared/vertical-slicing.md)), files to change, scope boundaries.
 
@@ -43,9 +46,9 @@ When working from a plan file or free-text (no issue number), use `<type>/<brief
 
 #### 1d. Execute
 
-Read AGENTS.md. Run pre-flight checks before the first phase (see [phase-execution](../forge-implement/references/phase-execution.md)). Implement in vertical phases — each phase spans all affected layers, includes tests, and ends with a commit. Run lint/types/tests at each phase gate.
+Read AGENTS.md. Run pre-flight checks before the first phase (see [phase-execution](../_shared/phase-execution.md)). Implement in vertical phases — each phase spans all affected layers, includes tests, and ends with a commit. Run lint/types/tests at each phase gate.
 
-After changing a pattern, grep for the old pattern across the appropriate scope and update all instances (see [pattern-audit](../forge-implement/references/pattern-audit.md)).
+After changing a pattern, grep for the old pattern across the appropriate scope and update all instances (see [pattern-audit](../_shared/pattern-audit.md)).
 
 #### 1e. Update docs
 

From 94ca3c118b59c1b527b085aa165bc38ae378e2d5 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 11:03:16 +0200
Subject: [PATCH 02/10] docs(context): align vocabulary with current skill
 behavior
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reflection described the removed four-reviewer design; Composite skill
claimed pure orchestration; Issue claimed an unpersisted AFK/HITL field
and a priority no skill uses; quality gates omitted coverage. Adds
Vertical phase and Tiny diff (both cross-skill and load-bearing),
removes Smart/Dumb zone and Three-tier context per the file's own
single-consumer rule — they live in architecture.md and setup-project.

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 CONTEXT.md | 26 +++++++++++++-------------
 1 file changed, 13 insertions(+), 13 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index f1989c6..f1616bd 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -6,47 +6,47 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Issue tracker** — system tracking Issues. Providers: GitHub (default, via `gh`), markdown `plan/` folder ([spec](skills/_shared/plan-folder-spec.md)), or user-configured (declared in AGENTS.md). Detection: AGENTS.md declaration → `plan/` directory → GitHub fallback.
 
-**Issue** — one tracked unit of work. Carries title, body, labels, and AFK/HITL mode.
+**Issue** — one tracked unit of work. Carries title, body, and labels; the AFK/HITL mode is recorded in the body at creation.
 
 **Plan** — structured proposal for implementing an Issue: durable decisions, vertical phases, verification steps.
 
 **Vertical slice** — end-to-end implementation crossing all layers for one narrow scenario, testable in isolation. See [vertical-slicing](skills/_shared/vertical-slicing.md).
 
+**Vertical phase** — one ordered step of a Plan: spans all affected layers, ends with tests passing and a commit. Phases sequence work within a Vertical slice.
+
 **AFK / HITL** — Issue execution mode. AFK: fully specified for autonomous execution. HITL: requires human judgment during implementation. Set at creation time. See [afk-vs-hitl](skills/forge-create-issue/references/afk-vs-hitl.md).
 
-**Reflection** — self-review across four parallel dimensions before peer review. Produces Findings.
+**Reflection** — self-review of current changes before peer review: tiny diffs review inline, otherwise one fresh-context review pass by default, deepened only when risk justifies it. Produces Findings.
+
+**Tiny diff** — roughly ≤2 files and ≤100 changed lines with low risk; reviewed inline without delegation. See [review-delegation](skills/_shared/review-delegation.md).
 
 **Finding** — one issue surfaced by reflection, severity-tagged P0–P3. P3 not flagged.
 
 **Deferred item** — a Finding not addressed in the current PR; becomes a new Issue.
 
-**Composite skill** — orchestrates other skills (currently only `forge-ship`).
+**Composite skill** — combines other skills' processes into a single invocation (currently only `forge-ship`, composing implement and reflect).
 
 **Inline fallback** — `(delegate)` step provides both sub-agent and in-context paths for runtime portability.
 
-**Self-containment** — single-use references stay with the skill; cross-skill references live in `skills/_shared/`. Within the shared layer, files have explicit consumers; outside it, skills are self-contained.
-
-**Smart zone / Dumb zone** — workable region (~first 100k tokens) vs degraded region of LLM context. See [architecture — Operating Constraints](docs/architecture.md#operating-constraints).
+**Self-containment** — single-use references stay with the skill; cross-skill references live in `skills/_shared/`. Within the shared layer, files have explicit consumers (skills or other shared files); outside it, skills are self-contained.
 
 **Pattern audit** — when a pattern changes, grep ALL files using the old pattern and update. See [pattern-audit](skills/_shared/pattern-audit.md).
 
-**Quality gates** — lint, format, type check, tests. Run before commit, PR push, and reflection.
+**Quality gates** — lint, format, type check, tests, and coverage (≥90% on new/modified code where tooling exists). Run at phase gates, before commit, PR push, and reflection.
 
 **Attended / unattended** — default pauses for confirmation; `--unattended` uses severity-gated heuristics.
 
 **Trailing context** — `-- <additional context>` appended to provide extra execution guidance.
 
-**Three-tier context** — Hot (`AGENTS.md`) / Warm (`docs/`) / Cold (specs). Each tier earns its token cost.
-
 ## Relationships
 
-- An **Issue** has one **AFK/HITL mode**, a priority, and labels.
-- A **Plan** implements one **Issue** through ordered **Vertical slices**.
+- An **Issue** has one **AFK/HITL mode** and labels.
+- A **Plan** implements one **Issue** through ordered **Vertical phases**.
 - A **Reflection** produces zero or more **Findings**; each is fixed or becomes a **Deferred item**.
-- A **Composite skill** invokes other skills; `--unattended` propagates through composition.
+- A **Composite skill** runs its component skills' processes; `--unattended` applies across all of them.
 
 ## Flagged Ambiguities
 
 - **Issue** (capitalized) is the abstract concept; provider determined per-project.
 - **Plan** is the proposal; "plan file" is a markdown artifact containing a Plan.
-- **Reflection** is self-review by sub-agents; **peer review** is external.
+- **Reflection** is self-review (inline for tiny diffs, otherwise delegated to fresh context); **peer review** is external.

From 5676d848aad0b56407ace4c2dd9ae997e57123f5 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 11:05:57 +0200
Subject: [PATCH 03/10] fix(skills): repair vocabulary, frontmatter, and
 structural drift
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- reflect: drop context: fork (forking the whole skill strands the
  interactive triage step; fresh context already comes from the
  (delegate) review step), rename Triage Deferred Items to Triage
  Findings — items only become deferred as the outcome of triage
- implement: document --unattended, fold Sub-Issue Handling into
  Step 1, action-verb step titles, placeholder casing, disambiguate
  from ship in the description
- ship: bash example for push/PR, coverage fallback, Format and
  Coverage rows in the output gates, scout delegation fallback
- create-issue/shape: complete allowed-tools their own steps require;
  create-issue gains trailing-context support and records the
  AFK/HITL mode in the Issue body
- address-pr-feedback: Follow-up renamed to Deferred item (canonical)
- issue-operations: new label discovery/update and epic sub-issue
  sections absorb the provider conditionals skills had inlined;
  sub-issue linking uses task lists with --parent as opt-in (the
  flag is not available on all gh versions)

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 skills/_shared/issue-operations.md            | 29 ++++++++++++++
 skills/_shared/plan-folder-spec.md            |  2 +-
 skills/forge-address-pr-feedback/SKILL.md     | 16 ++++----
 skills/forge-create-issue/SKILL.md            | 27 +++++++------
 skills/forge-implement/SKILL.md               | 38 +++++++++----------
 skills/forge-reflect/SKILL.md                 | 21 +++++-----
 skills/forge-setup-project/SKILL.md           | 11 +++---
 .../references/output-format.md               |  6 +--
 skills/forge-shape/SKILL.md                   | 14 ++++---
 skills/forge-ship/SKILL.md                    | 22 +++++++----
 10 files changed, 115 insertions(+), 71 deletions(-)

diff --git a/skills/_shared/issue-operations.md b/skills/_shared/issue-operations.md
index 0bf13a4..f82ccef 100644
--- a/skills/_shared/issue-operations.md
+++ b/skills/_shared/issue-operations.md
@@ -29,6 +29,35 @@ ISSUE_EOF
 
 **Other provider:** use the tool or CLI declared in AGENTS.md with the same title, body, and labels.
 
+## Discover and Update Labels
+
+**GitHub:** discover available labels before applying any, and add missing ones to an existing Issue:
+
+```bash
+gh label list
+gh issue edit <ISSUE_NUMBER> --add-label "<LABEL>"
+```
+
+**Markdown:** choose labels freely — there is no predefined set; edit the issue file's `labels` frontmatter.
+
+**Other provider:** use the declared tool's label operations.
+
+## Create Epic with Sub-Issues
+
+Create the parent Issue first, then the sub-issues.
+
+**GitHub:** link sub-issues from the parent body with a task list — this works on every `gh` version:
+
+```markdown
+- [ ] #<SUB_ISSUE_NUMBER>
+```
+
+Newer `gh` versions also support `gh issue create --parent <PARENT_NUMBER>` for native sub-issues; verify the flag exists before relying on it.
+
+**Markdown:** list sub-issue IDs in the parent issue file's body.
+
+**Other provider:** use the declared tool's hierarchy mechanism, or fall back to referencing sub-issue IDs in the parent body.
+
 ## Read Issue
 
 Given an issue ID:
diff --git a/skills/_shared/plan-folder-spec.md b/skills/_shared/plan-folder-spec.md
index da59b19..b5b2b18 100644
--- a/skills/_shared/plan-folder-spec.md
+++ b/skills/_shared/plan-folder-spec.md
@@ -43,7 +43,7 @@ created: 2026-04-30
 | `mode` | No | `AFK` or `HITL` (defaults to `HITL`) |
 | `created` | Yes | ISO date |
 
-The body below the frontmatter uses the same structure as any forge issue: Summary, Problem / Motivation, Proposed Solution, Acceptance Criteria.
+The body below the frontmatter uses the same structure as any forge Issue: Summary, Problem / Motivation, Proposed Solution (with Alternatives Considered and Implementation Constraints when applicable), Acceptance Criteria.
 
 ## INDEX.md format
 
diff --git a/skills/forge-address-pr-feedback/SKILL.md b/skills/forge-address-pr-feedback/SKILL.md
index b941ba7..4a3b328 100644
--- a/skills/forge-address-pr-feedback/SKILL.md
+++ b/skills/forge-address-pr-feedback/SKILL.md
@@ -2,7 +2,7 @@
 name: forge-address-pr-feedback
 description: Analyze and address unresolved feedback on a GitHub pull request. Use when the user has received PR review comments and wants to systematically address each piece of feedback, or when the user mentions PR feedback, review comments, or addressing reviewer concerns.
 disable-model-invocation: true
-allowed-tools: Read, Edit, Write, Bash, Grep, Glob
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob, AskUserQuestion
 ---
 
 # Address PR Feedback
@@ -11,7 +11,7 @@ Systematically address unresolved review feedback on a pull request.
 
 ## Input
 
-PR number or URL (auto-detects from current branch if omitted). Optional: `-- <additional context>` for prioritization guidance.
+PR number or URL (`$ARGUMENTS`; auto-detects from current branch if omitted). Optional: `-- <additional context>` for prioritization guidance.
 
 ## Process
 
@@ -56,7 +56,9 @@ For each unresolved thread, read the file and surrounding context, then categori
 - **Discussion** — assess if change improves code
 - **Already addressed** — thread not resolved but change was made
 - **Won't fix** — current approach is preferred
-- **Follow-up** — valid but out of scope — create linked issue
+- **Deferred** — valid but out of scope — becomes a Deferred item (new Issue)
+
+For **Discussion** threads where the decision is genuinely the user's to make, ask via AskUserQuestion instead of assuming.
 
 ### Step 3: Address and Reply Individually
 
@@ -87,11 +89,11 @@ Reply format by category:
 - **Discussion**: "<decision and reasoning>"
 - **Already addressed**: "Addressed in `<sha>`."
 - **Won't fix**: "Keeping current approach because <reason>."
-- **Follow-up**: "Created #<num> to track this."
+- **Deferred**: "Created #<num> to track this."
 
-### Step 4: Create Follow-up Issues
+### Step 4: Create Issues for Deferred Items
 
-For valid out-of-scope improvements, create an Issue in the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Include the PR context: reviewer's comment, PR number, and proposed solution.
+For each Deferred item, create an Issue in the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Include the PR context: reviewer's comment, PR number, and proposed solution.
 
 ### Step 5: Push and Summarize
 
@@ -99,7 +101,7 @@ For valid out-of-scope improvements, create an Issue in the project's Issue trac
 git push
 ```
 
-Report: feedback items addressed, commits created, follow-up issues created, items needing human decision.
+Report: threads addressed, commits created, Deferred items created, items needing human decision.
 
 ## Guidelines
 
diff --git a/skills/forge-create-issue/SKILL.md b/skills/forge-create-issue/SKILL.md
index 3b74ee9..99599f4 100644
--- a/skills/forge-create-issue/SKILL.md
+++ b/skills/forge-create-issue/SKILL.md
@@ -1,19 +1,21 @@
 ---
 name: forge-create-issue
-description: Collaboratively plan and create well-structured Issues through interactive discussion. Use when the user wants to create an Issue, plan a feature, report a bug, or scope out work for implementation. Supports GitHub, markdown plan/ folder, and other providers.
+description: Collaboratively plan and create well-structured Issues through interactive discussion. Use when the user wants to create an Issue, report a bug, or scope out work that is already understood — use forge-shape first when the idea is still vague. Supports GitHub, markdown plan/ folder, and other providers.
 disable-model-invocation: true
-allowed-tools: Read, Bash, Grep, Glob, WebSearch
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob, WebSearch, AskUserQuestion
 ---
 
 # Create Issue
 
-Collaboratively plan and create well-structured Issues through interactive discussion. The Issue is created in the project's Issue tracker — see [CONTEXT.md](../../CONTEXT.md) for provider detection.
+Collaboratively plan and create well-structured Issues through interactive discussion. The Issue is created in the project's Issue tracker — see [issue-operations](../_shared/issue-operations.md) for provider detection.
 
 ## Input
 
-The issue idea or problem description: $ARGUMENTS
+The Issue idea or problem description: $ARGUMENTS
 
-If no argument is provided, ask the user what they'd like to create an issue for.
+Optional: `-- <additional context>` for execution guidance.
+
+If no argument is provided, ask the user what they'd like to create an Issue for.
 
 ## Process
 
@@ -46,7 +48,7 @@ For each approach:
 - Relative complexity (Low / Medium / High)
 - Key files affected
 
-Let the user choose or combine approaches.
+Let the user choose or combine approaches via AskUserQuestion.
 
 ### Step 4: Assess Scope
 
@@ -64,7 +66,7 @@ If splitting makes sense, offer: single Issue, multiple linked Issues, or epic w
 
 **Title:** Use conventional commit format — `<type>(<scope>): <description>`
 
-**Labels:** When using GitHub, discover available labels with `gh label list`. When using the markdown provider, choose labels freely — there is no predefined set. Apply at least one type label and relevant area labels.
+**Labels:** Discover what labels exist before applying any — see [issue-operations](../_shared/issue-operations.md). Apply at least one type label and relevant area labels.
 
 **Body structure:**
 
@@ -72,6 +74,8 @@ If splitting makes sense, offer: single Issue, multiple linked Issues, or epic w
 ## Summary
 [1-2 sentences]
 
+**Execution mode:** [AFK | HITL]
+
 ## Problem / Motivation
 [Why this needs to exist]
 
@@ -92,11 +96,9 @@ If splitting makes sense, offer: single Issue, multiple linked Issues, or epic w
 
 ### Step 6: Review and Create
 
-Present the draft to the user. Iterate until satisfied. Then create the Issue using the project's Issue tracker — see [issue-operations](../_shared/issue-operations.md) for provider-specific mechanics.
-
-For GitHub epics, create the parent issue first, then sub-issues with `--parent <PARENT_NUMBER>`.
+Present the draft to the user and iterate until satisfied (use AskUserQuestion for approve/revise decisions). Then create the Issue using the project's Issue tracker — see [issue-operations](../_shared/issue-operations.md) for provider-specific mechanics, including epics with sub-issues.
 
-Share the issue reference. Suggest using `forge-implement` to start implementation.
+Share the Issue reference. Suggest using `forge-implement` to start implementation.
 
 ## Guidelines
 
@@ -108,11 +110,12 @@ Share the issue reference. Suggest using `forge-implement` to start implementati
 
 ## Related Skills
 
-**Next step:** Use `forge-implement` to implement the issue.
+**Next step:** Use `forge-implement` to implement the Issue.
 
 ## Example Usage
 
 ```
 /forge-create-issue add dark mode support
+/forge-create-issue add dark mode support -- keep it to a single Issue
 /forge-create-issue
 ```
diff --git a/skills/forge-implement/SKILL.md b/skills/forge-implement/SKILL.md
index fe5a5c4..e76bfce 100644
--- a/skills/forge-implement/SKILL.md
+++ b/skills/forge-implement/SKILL.md
@@ -1,24 +1,26 @@
 ---
 name: forge-implement
-description: Implement a feature or fix from an Issue, plan file, or free-text description, following project standards. Use when the user wants to start working on an Issue, implement a feature, fix a bug, or build from a plan or roadmap.
+description: Implement a feature or fix from an Issue, plan file, or free-text description, following project standards. Use when the user wants to start working on an Issue, implement a feature, or fix a bug. Stops after opening the PR — use forge-ship to also run review.
 disable-model-invocation: true
 ---
 
-# Implement
+# Implement a Change
 
 Implement a feature or fix following project standards.
 
 ## Input
 
-Primary input: an Issue number/URL, a plan file path, or free-text description. Optional: `-- <additional context>` for execution guidance.
+Primary input (`$ARGUMENTS`): an Issue number/URL, a plan file path, or free-text description. Optional: `-- <additional context>` for execution guidance.
+
+**Unattended mode:** `--unattended` skips plan approval and proceeds without confirmation prompts.
 
 ## Process
 
 ### Step 1: Understand the Work
 
-Determine the input type and extract requirements. Detect the Issue tracker provider (see [CONTEXT.md](../../CONTEXT.md)).
+Determine the input type and extract requirements. Detect the Issue tracker provider (see [issue-operations](../_shared/issue-operations.md)).
 
-- **Issue** — fetch using the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Parse title, requirements, acceptance criteria, labels, sub-issues, comments. Add labels if missing.
+- **Issue** — fetch using the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Parse title, requirements, acceptance criteria, labels, sub-issues, comments. Add labels if missing. When the Issue has sub-issues, treat each as a separate task and close them as you complete them.
 - **Plan file** — extract goals, requirements, constraints, acceptance criteria.
 - **Free-text** — parse scope and constraints. Ask clarifying questions if underspecified.
 
@@ -28,7 +30,7 @@ Flag for user input if: vague criteria, `discovery` label, scope too large, or d
 
 Identify **durable architectural decisions** — data model, API contracts, and module boundaries that absorb change instead of exposing internals. Prefer interfaces that stay simpler than their implementations; avoid pass-through wrappers and shallow seams.
 
-**For complex work**, delegate codebase research to a sub-agent for unbiased findings:
+**For complex work**, delegate codebase research to a sub-agent for unbiased answers:
 
 #### Research (delegate)
 
@@ -50,13 +52,14 @@ Present the plan via AskUserQuestion. Get user confirmation before coding. **In
 ### Step 3: Create Feature Branch
 
 ```bash
+# Sync the default branch, then branch off it
 git fetch origin
 git checkout $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
 git pull
-git checkout -b <type>/<issue-number>-<brief-description>
+git checkout -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION>
 ```
 
-When working from a plan file or free-text (no issue number), use a descriptive slug: `<type>/<brief-description>`.
+When working from a plan file or free-text (no Issue number), use a descriptive slug: `<TYPE>/<BRIEF_DESCRIPTION>`.
 
 ### Step 4: Implement
 
@@ -67,12 +70,12 @@ Execute the work in vertical phases:
 - **Per phase** — implement end to end across all needed layers, keep tests close to the behavior, and verify unfamiliar APIs before using them.
 - **Phase gate** — before moving on, run relevant tests/checks, confirm no new lint/type failures, and commit one logical change.
 
-### Step 5: Pattern Consistency Audit
+### Step 5: Audit Pattern Consistency
 
 If you changed a pattern (error handling, component structure, API convention), grep for every other file using the old pattern and update them too:
 
 ```bash
-grep -rn "<pattern>" <search-root>/
+grep -rn "<PATTERN>" <SEARCH_ROOT>/
 ```
 
 Audit the **pattern shape**, not just a literal string. Choose the right search scope, re-grep after updating, and note any intentional exceptions in the PR.
@@ -84,7 +87,7 @@ If behavior changed, update:
 - `AGENTS.md` — if conventions or patterns changed
 - Code comments — only where logic isn't self-evident
 
-### Step 7: Final Quality Gate
+### Step 7: Run Final Quality Gate
 
 Run all project quality checks (discover from AGENTS.md, project docs, or repository scripts):
 
@@ -99,16 +102,16 @@ Fix issues and commit fixes.
 ### Step 8: Push and Create PR
 
 ```bash
-git push -u origin <branch-name>
+git push -u origin <BRANCH_NAME>
 ```
 
-Create PR with conventional commit title format. Lead the summary with **why** the change was needed — pull the motivation from the linked issue's problem statement; if no issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: list of changes, test plan checklist, and quality checklist. Close the issue when one exists.
+Create PR with conventional commit title format. Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: list of changes, test plan checklist, and quality checklist. Close the Issue when one exists.
 
 If the implementation requires manual deployment steps (env vars, infra changes, container/runtime config, migrations), add a prominent `> [!WARNING]` block at the top of the PR body.
 
-### Step 9: Summary
+### Step 9: Summarize
 
-Report: branch name, PR link, commits made, files changed, tests added, docs updated, follow-up items.
+Report: branch name, PR link, commits made, files changed, tests added, docs updated, deferred items.
 
 ## Guidelines
 
@@ -116,10 +119,6 @@ Report: branch name, PR link, commits made, files changed, tests added, docs upd
 - **Ask when unsure** — better to clarify than implement wrong
 - **Don't scope creep** — implement what was asked, nothing more
 
-## Sub-Issue Handling
-
-When working from an Issue with sub-issues, treat each as a separate task. Close sub-issues as you complete them.
-
 ## Related Skills
 
 **After implementing:** Use `forge-reflect` to self-review before requesting review.
@@ -130,6 +129,7 @@ When working from an Issue with sub-issues, treat each as a separate task. Close
 ```
 /forge-implement 123
 /forge-implement 123 -- keep the diff minimal and prefer existing UI patterns
+/forge-implement --unattended 123
 /forge-implement docs/roadmap.md
 /forge-implement add a dark mode toggle to the settings page
 ```
diff --git a/skills/forge-reflect/SKILL.md b/skills/forge-reflect/SKILL.md
index cfec6c1..e8acade 100644
--- a/skills/forge-reflect/SKILL.md
+++ b/skills/forge-reflect/SKILL.md
@@ -1,11 +1,10 @@
 ---
 name: forge-reflect
-description: Review current changes with a lean review flow. Works on a PR, branch diff, or uncommitted changes. Tiny low-risk diffs stay inline; larger or riskier changes use fresh-context review. Use when the user wants to self-review before committing, pushing, or requesting peer review.
-context: fork
+description: Self-review current changes — a PR, branch diff, or uncommitted work. Use when the user wants a code review of their changes, a self-review before committing or pushing, or a final check before requesting peer review.
 disable-model-invocation: true
 ---
 
-# Reflect
+# Reflect on Changes
 
 Self-review current changes before committing, pushing, or requesting peer review.
 
@@ -61,7 +60,7 @@ Follow the [review-delegation](../_shared/review-delegation.md) process: collect
 
 **Expected output:** Deduplicated findings grouped by file with severity tags (P0/P1/P2).
 
-### Step 3: Quality Gates
+### Step 3: Run Quality Gates
 
 Run the project's lint, format, type check, and test commands. Fix issues and commit fixes.
 
@@ -69,18 +68,18 @@ Run the project's lint, format, type check, and test commands. Fix issues and co
 
 Aggregate findings from all review passes (Step 2) with quality gate results (Step 3) into the summary format below. Deduplicate any findings flagged by multiple passes — keep the highest severity.
 
-### Step 5: Triage Deferred Items
+### Step 5: Triage Findings
 
-Present each deferred improvement to the user and ask whether to **fix now** or **defer as a follow-up issue**.
+Present each Finding to the user via AskUserQuestion and ask whether to **fix now** or **defer**.
 
-Bias hard toward **fix now**. Recommend deferral only when the finding is truly out of scope, materially expands the PR, or needs separate design/review.
+Bias hard toward **fix now**. Recommend deferral only when the Finding is truly out of scope, materially expands the PR, or needs separate design/review.
 
-For each item, recommend one of:
+For each Finding, recommend one of:
 - **Fix now** — default for in-scope findings and small follow-up work (e.g., missing tests, stale docs, duplicated lines, modest refactors that fit the current change)
 - **Defer** — only for larger or truly out-of-scope changes (e.g., a cross-cutting refactor, a new feature, a separate migration strategy)
 
 State your recommendation and let the user decide. Then:
-- **Fix now items:** apply the fix and commit it
+- **Fix now:** apply the fix and commit it
 - **Deferred items:** create an Issue in the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)) with context and proposed solution
 
 ## Output Format
@@ -94,9 +93,9 @@ State your recommendation and let the user decide. Then:
 #### <file>
 - [P0/P1/P2] <finding>
 
-### Deferred Items
+### Finding Triage
 - Fixed: <what was addressed>
-- Created #<num>: <title>
+- Deferred #<num>: <title>
 - (or: None identified)
 
 ### Quality Gates
diff --git a/skills/forge-setup-project/SKILL.md b/skills/forge-setup-project/SKILL.md
index 8bec9da..c131194 100644
--- a/skills/forge-setup-project/SKILL.md
+++ b/skills/forge-setup-project/SKILL.md
@@ -21,7 +21,7 @@ Set up or update a project's context infrastructure for agentic engineering. Con
 
 ## Input
 
-Optional project root path (defaults to cwd). Optional: `-- <additional context>` for execution guidance.
+Optional project root path (`$ARGUMENTS`; defaults to cwd). Optional: `-- <additional context>` for execution guidance.
 
 ## Process
 
@@ -103,9 +103,10 @@ Only create docs with actual content. An empty doc wastes context.
 
 All Tier 2 docs must pass the undiscoverability test. Use tables for structured data. Include actual file paths.
 
-### Step 7: Compatibility Symlink and .gitignore
+### Step 7: Create Compatibility Symlink and Update .gitignore
 
 ```bash
+# Replace any legacy CLAUDE.md with a symlink to the canonical AGENTS.md
 rm -f CLAUDE.md
 ln -sf AGENTS.md CLAUDE.md
 ```
@@ -114,11 +115,11 @@ If the platform doesn't support symlinks, stop and tell the user.
 
 Create or update `.gitignore` with entries matching the detected stack. Never overwrite an existing `.gitignore` — append only missing entries.
 
-### Step 8: Human-Facing Files
+### Step 8: Create Human-Facing Files
 
 Create if it doesn't exist (this is for humans, not agent context):
 
-- **README.md** — project description, quick start, docs links. If one exists, ask: replace, merge, or keep?
+- **README.md** — project description, quick start, docs links. If one exists, ask via AskUserQuestion: replace, merge, or keep?
 
 ### Step 9: Commit
 
@@ -128,7 +129,7 @@ Stage and commit all new/modified files:
 
 Do not commit if: dry run requested, unrelated staged changes exist, or generated files have unresolved questions.
 
-### Step 10: Summary
+### Step 10: Summarize
 
 Report what was created/changed. See [output-format.md](references/output-format.md) for the structure. Include tier status with line counts, agent readiness assessment, and next steps.
 
diff --git a/skills/forge-setup-project/references/output-format.md b/skills/forge-setup-project/references/output-format.md
index 6cb2dff..b8c8fa1 100644
--- a/skills/forge-setup-project/references/output-format.md
+++ b/skills/forge-setup-project/references/output-format.md
@@ -36,7 +36,7 @@ Use the appropriate format based on mode.
 1. Fill any <!-- TODO --> markers
 2. Add failure modes as you encounter agent mistakes
 3. Re-run /forge-setup-project periodically
-4. Use /forge-create-issue to plan your first piece of work
+4. Use /forge-create-issue to plan your first piece of work — or /forge-shape if the idea is still rough
 ```
 
 ## Audit / Legacy Migration Mode
@@ -56,11 +56,11 @@ Use the appropriate format based on mode.
 | App legibility | <status> | <action> |
 | Known risks | <risks> | <where documented> |
 
-### Recommendations Deferred
+### Recommendations Not Applied
 <items the user chose not to apply>
 
 ### Next Steps
 1. Review changes and verify accuracy
-2. Revisit deferred recommendations
+2. Revisit recommendations not applied
 3. Re-run /forge-setup-project periodically
 ```
diff --git a/skills/forge-shape/SKILL.md b/skills/forge-shape/SKILL.md
index 9da79a1..6b042cb 100644
--- a/skills/forge-shape/SKILL.md
+++ b/skills/forge-shape/SKILL.md
@@ -2,10 +2,10 @@
 name: forge-shape
 description: Shape a vague idea into a clear plan through codebase investigation and convergent one-at-a-time questioning. Use when the user has a rough idea or problem that needs specifying before issue creation.
 disable-model-invocation: true
-allowed-tools: Read, Bash, Grep, Glob, WebSearch, AskUserQuestion
+allowed-tools: Read, Edit, Write, Bash, Grep, Glob, WebSearch, AskUserQuestion
 ---
 
-# Shape
+# Shape a Problem
 
 Shape a problem and converge on a plan before creating issues.
 
@@ -13,7 +13,7 @@ Shape a problem and converge on a plan before creating issues.
 
 The idea or problem to shape: $ARGUMENTS
 
-Optional last parameter: `-- <additional context>`
+Optional: `-- <additional context>` for execution guidance.
 
 If no argument is provided, ask the user what they'd like to shape.
 
@@ -36,7 +36,7 @@ If CONTEXT.md exists, read it — use its vocabulary when framing questions and
 
 Loop until the design concept is clear:
 
-1. Ground the next question in Step 1 findings — never ask what the codebase already answers
+1. Ground the next question in Step 1 facts — never ask what the codebase already answers
 2. Ask one question with your recommended answer (phrase as "I'd suggest X because Y", not as a decision)
 3. Wait for the user's response
 4. **Challenge when warranted** — if the answer conflicts with CONTEXT.md vocabulary, call it out. If it contradicts what the code does, surface it. If it uses vague or overloaded terms, propose a precise canonical term. Invent concrete scenarios to stress-test fuzzy boundaries.
@@ -50,7 +50,9 @@ Stop when the user has accepted recommended answers for several consecutive ques
 
 **Use AskUserQuestion** for each individual question. Do not bundle multiple questions into one prompt — that defeats the methodology.
 
-### Step 3: Explore Approaches (delegate, optional)
+### Step 3: Explore Approaches (delegate)
+
+**This step is optional.**
 
 If shaping in Step 2 surfaced a clear approach, skip this step and go to Step 4.
 
@@ -74,7 +76,7 @@ Assign each sub-agent one constraint lens (adapt to the problem):
 > - Risk factors
 
 **Inputs provided to each sub-agent:**
-- Codebase findings from Step 1
+- Codebase facts from Step 1
 - Shaped design concept from Step 2
 - The specific constraint lens to apply
 
diff --git a/skills/forge-ship/SKILL.md b/skills/forge-ship/SKILL.md
index 1a3271b..477a8f0 100644
--- a/skills/forge-ship/SKILL.md
+++ b/skills/forge-ship/SKILL.md
@@ -4,13 +4,13 @@ description: End-to-end implementation and self-review in a single invocation. I
 disable-model-invocation: true
 ---
 
-# Ship
+# Ship a Change
 
 Implement end to end — code it, review it, ship it. Implementation runs in the current session; tiny low-risk diffs review inline, otherwise review uses one fresh-context reviewer by default and deepens only when risk justifies it.
 
 ## Input
 
-Same as `forge-implement`: Issue number/URL, plan file path, or free-text. Optional: `-- <additional context>`.
+Same as `forge-implement` (`$ARGUMENTS`): Issue number/URL, plan file path, or free-text. Optional: `-- <additional context>`.
 
 **Unattended mode:** `--unattended` skips plan approval and auto-triages findings by severity.
 
@@ -36,13 +36,14 @@ Present the plan via AskUserQuestion. **In unattended mode:** skip approval and
 #### 1c. Branch
 
 ```bash
+# Sync the default branch, then branch off it
 git fetch origin
 git checkout $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
 git pull
-git checkout -b <type>/<issue-number>-<brief-description>
+git checkout -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION>
 ```
 
-When working from a plan file or free-text (no issue number), use `<type>/<brief-description>`.
+When working from a plan file or free-text (no Issue number), use `<TYPE>/<BRIEF_DESCRIPTION>`.
 
 #### 1d. Execute
 
@@ -60,11 +61,16 @@ Update `docs/*.md` and `AGENTS.md` if behavior or conventions changed.
 - [ ] Format — no violations
 - [ ] Type check — no errors
 - [ ] All tests pass
-- [ ] Test coverage ≥ 90% for new/modified code
+- [ ] Test coverage ≥ 90% for new/modified code — if coverage tooling is not configured, flag this to the user and offer to set it up
 
 #### 1g. Push and create PR
 
-Push branch, create PR with conventional commit title. Lead the summary with **why** the change was needed — pull the motivation from the linked issue's problem statement; if no issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: changes list, test plan, quality checklist. Close the issue when one exists. Add a `> [!WARNING]` block for manual deployment steps.
+```bash
+git push -u origin <BRANCH_NAME>
+gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body "<PR_BODY>"
+```
+
+Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: changes list, test plan, quality checklist. Close the Issue when one exists. Add a `> [!WARNING]` block for manual deployment steps.
 
 Do not produce the implementation summary yet — the review will inform the final report.
 
@@ -90,7 +96,7 @@ Bias hard toward **fix now**:
 
 For both modes, deferred items become Issues — see [issue-operations](../_shared/issue-operations.md) for provider-specific mechanics.
 
-### Step 4: Summary
+### Step 4: Summarize
 
 Report implementation and review results together.
 
@@ -113,8 +119,10 @@ Report implementation and review results together.
 
 ### Quality Gates
 - Lint: ✓/✗
+- Format: ✓/✗
 - Types: ✓/✗
 - Tests: ✓/✗
+- Coverage: ✓/✗/not configured
 ```
 
 ## Guidelines

From 3124acad77610e9094aed2288eb301eff42561ee Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 11:07:24 +0200
Subject: [PATCH 04/10] docs: sync consistency table, architecture tree, and
 validation lists

The Cross-Skill Consistency table's Referenced In column predated
forge-ship's extraction from implement and missed it in ~8 rows; the
architecture tree omitted the three most-consumed _shared files and
listed directories that no longer exist; testing/development check
lists enumerated only 5 of 7 skills; README counted six skills; the
architecture Operating Constraints table said ~150-200 instructions
per skill where coding-guidelines says under ~35.

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 README.md                 |  2 +-
 docs/architecture.md      | 26 +++++++++++++-------------
 docs/coding-guidelines.md | 27 ++++++++++++++-------------
 docs/development.md       |  7 +------
 docs/testing.md           | 11 +++--------
 5 files changed, 32 insertions(+), 41 deletions(-)

diff --git a/README.md b/README.md
index 3fdc8b5..6de15fb 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 <p align="center">
   <strong>Agent skills for structured development with pluggable issue tracking.</strong><br>
-  One workflow. Six skills. From idea to review-ready code.
+  One workflow. Seven skills. From idea to review-ready code.
 </p>
 
 <p align="center">
diff --git a/docs/architecture.md b/docs/architecture.md
index c805493..bee7443 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -14,22 +14,22 @@ forge/
 │   │   ├── SKILL.md
 │   │   └── references/shaping-methodology.md  # One-at-a-time questioning philosophy
 │   ├── _shared/                           # Cross-skill references (see coding-guidelines.md)
+│   │   ├── issue-operations.md            # Provider detection and Issue CRUD
 │   │   ├── plan-folder-spec.md            # Markdown issue tracker provider spec
+│   │   ├── review-delegation.md           # Lean review flow: inline vs fresh-context passes
 │   │   ├── review-rubric.md               # P0–P3 severity taxonomy
 │   │   ├── review-dimensions.md           # Lean review checklists: default pass + optional deep passes
+│   │   ├── vertical-slicing.md            # Thin end-to-end slicing philosophy
+│   │   ├── phase-execution.md             # Pre-flight, per-phase loop, phase gates
+│   │   ├── pattern-audit.md               # Pattern consistency audit checklist
 │   │   ├── deep-modules.md                # Module depth audit checklist
 │   │   ├── barrel-imports.md              # Import structure discipline
-│   │   └── roles/forge-reviewer.md        # Review agent persona
+│   │   └── roles/                         # Cross-skill personas: forge-reviewer, forge-scout
 │   ├── forge-create-issue/
 │   │   ├── SKILL.md                       # Step 1: Plan and create Issues (provider-agnostic)
-│   │   └── references/                    # Slicing philosophy, AFK/HITL
-│   ├── forge-implement/
-│   │   ├── SKILL.md                       # Step 2: Implement from issue, plan, or description
-│   │   ├── references/                    # Progressive disclosure: implementation craft companions
-│   │   └── roles/forge-scout.md           # Blind codebase research persona
-│   ├── forge-reflect/
-│   │   ├── SKILL.md                       # Step 3: Self-review changes (PR, branch, or uncommitted)
-│   │   └── references/                    # (shared references moved to _shared/)
+│   │   └── references/                    # AFK/HITL classification
+│   ├── forge-implement/SKILL.md           # Step 2: Implement from Issue, plan, or description
+│   ├── forge-reflect/SKILL.md             # Step 3: Self-review changes (PR, branch, or uncommitted)
 │   ├── forge-address-pr-feedback/SKILL.md # Step 4: Address PR review comments
 │   └── forge-ship/SKILL.md                # Composite: implement + review in one invocation
 ├── docs/                                  # Project documentation
@@ -77,12 +77,12 @@ Practitioners call the workable region the **smart zone** and the degraded regio
 | Fresh-context review (`forge-reflect`, `forge-ship`) | Tiny low-risk diffs can stay inline; otherwise one reviewer starts in smart zone by default, and depth is added only when risk justifies it |
 | Progressive disclosure (`references/`) | Load companion philosophy on demand instead of always-loading every skill's full content |
 | Three-tier context model (`AGENTS.md` / `docs/` / specs) | Each tier earns its always-loaded cost; cold tier loads only when needed |
-| Instruction budget (~150–200 instructions per skill body) | Skills stay lean enough to compose without exceeding what frontier LLMs follow consistently |
+| Instruction budget (under ~35 instructions per skill body) | Skills stay lean enough to compose without exceeding the ~150–200 instructions frontier LLMs follow consistently |
 | Role files (`roles/*.md`) | Sub-agents start with focused persona context, not the parent's accumulated history |
 
 The smart-zone constraint is approximate, model-dependent, and changing — but treating it as a real boundary tends to produce more reliable workflows than assuming the advertised context size is the working size. When a skill's design feels like it has too many moving parts to fit in one head, that is also approximately when it has too many tokens to fit in the smart zone.
 
-The instruction-budget figure (~150–200 instructions) is a related but distinct constraint covered in [coding-guidelines.md](coding-guidelines.md#instruction-budget) — it concerns how many discrete instructions an LLM follows reliably, separately from how many tokens fit in the smart zone.
+The instruction-budget figures (~150–200 followed reliably overall, under ~35 per skill) are a related but distinct constraint covered in [coding-guidelines.md](coding-guidelines.md#instruction-budget) — they concern how many discrete instructions an LLM follows reliably, separately from how many tokens fit in the smart zone.
 
 ## Design Decisions
 
@@ -93,11 +93,11 @@ The instruction-budget figure (~150–200 instructions) is a related but distinc
 | GraphQL for PR threads | Required in address-pr-feedback | REST API doesn't expose `isResolved` on review threads |
 | AskUserQuestion | Used for interactive skills | Structured user input with options, not free-form |
 | Pipeline linking | Each skill's "Related Skills" section | Skills reference the next step so users discover the workflow |
-| Sub-agent delegation | `context: fork` frontmatter + `(delegate)` step pattern | Fresh context for unbiased review; `context: fork` is the native mechanism in Claude Code, `(delegate)` is the cross-runtime fallback |
+| Sub-agent delegation | `(delegate)` step pattern; `context: fork` frontmatter available for whole-skill forking | Fresh context for unbiased review; `(delegate)` works across runtimes, `context: fork` is Claude Code's native whole-skill mechanism — unsuitable for skills with interactive steps |
 | Skill composition | Composite skills reference other skills by path | Keeps orchestrators lean; avoids duplicating step-level instructions across skills |
 | Tool-layer integration | Skills reference external tools by name, not by import | Runtimes and extensions expose delegation/model-selection capabilities; skills use them when available and fall back when not — zero coupling. Runtime-specific agent files or presets are optional local tuning, not part of Forge. When a runtime couples agent names to model/provider selection, push role content, prefer inheriting the parent session configuration over hard-coded agent IDs, use cheap fast models for factual scouting, and prefer cheaper review-capable models for routine review work |
 | Reusable roles | Skill-specific: `<skill>/roles/*.md`; cross-skill: `_shared/roles/*.md` | Delegation personas separated from skill body; single-use roles co-locate with the skill, shared roles live in `_shared/` |
-| Blind research delegation | Scout researches codebase without seeing the ticket | Knowing the goal causes opinions to leak into research — objective facts lead to better planning |
+| Blind research delegation | Scout researches codebase without seeing the Issue | Knowing the goal causes opinions to leak into research — objective facts lead to better planning |
 | Vertical implementation phases | Each phase is a thin end-to-end slice, not a horizontal layer | Horizontal plans (all DB, then all services, then all API) produce untestable intermediate states |
 | Three-tier context model | Hot (`AGENTS.md`) / Warm (`docs/`) / Cold (specs) | Generic context hurts agent performance — tiered model ensures each doc earns its token cost |
 | Compatibility layer | `CLAUDE.md` symlink to `AGENTS.md` | Preserve compatibility without making vendor-specific filenames canonical |
diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 5735c66..094b940 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -19,7 +19,7 @@ Every skill follows the same section order:
 ## Frontmatter Conventions
 
 - `name`: kebab-case, prefixed with `forge-` (e.g., `forge-setup-project`)
-- `description`: one sentence describing what the skill does and when to use it. This text is what compatible agents use for skill discovery, so it must be descriptive.
+- `description`: one or two sentences describing what the skill does and when to use it. This text is what compatible agents use for skill discovery, so it must be descriptive.
 - `disable-model-invocation`: set to `true` for skills that should only be invoked by the user via slash command (workflow entry points). Omit or set to `false` for skills that agents may auto-activate.
 - `allowed-tools`: comma-separated list of tools the skill may use. Omit to allow all tools.
 
@@ -29,6 +29,7 @@ Every skill follows the same section order:
 - Include bash examples for any CLI operations (especially `gh` and `git` commands)
 - Use `AskUserQuestion` for user decisions — never assume
 - Steps should be numbered sequentially and named with action verbs: "Create", "Fetch", "Analyze", "Generate"
+- Composite skills may subdivide a wrapping step into lettered sub-steps (`#### 1a. <Action>`) when inlining a component skill's flow
 
 ## Writing Delegate Steps
 
@@ -50,7 +51,7 @@ Both can coexist in the same skill — `context: fork` handles Claude Code, `(de
 
 ### Using Roles in Delegate Steps
 
-When a delegation step benefits from a separated persona, extract it into a **role file** under the skill's `roles/` directory (see [Architecture — Role File Format](architecture.md#role-file-format)). The skill then references the role and provides only task-specific instructions:
+When a delegation step benefits from a separated persona, extract it into a **role file** under the skill's `roles/` directory (see [Architecture — Skill & Role File Format](architecture.md#skill--role-file-format)). The skill then references the role and provides only task-specific instructions:
 
 ```markdown
 #### Research (delegate)
@@ -103,27 +104,27 @@ Conventions shared across skills. When modifying any, update every skill that re
 
 | Convention | Format | Referenced In |
 |------------|--------|---------------|
-| Conventional commits | `<type>(<scope>): <description>` — titles, branches, commits, PRs | create-issue, implement, address-pr-feedback |
-| Canonical guidance file | `AGENTS.md` canonical; `CLAUDE.md` compatibility symlink | setup-project, implement, reflect |
+| Conventional commits | `<type>(<scope>): <description>` — titles, branches, commits, PRs | create-issue, shape, implement, ship, address-pr-feedback |
+| Canonical guidance file | `AGENTS.md` canonical; `CLAUDE.md` compatibility symlink | setup-project, implement, ship |
 | Validate approach | Present plan and get user confirmation before implementing (skipped in unattended mode) | implement, ship |
-| Phase execution | Pre-flight, per-phase implementation/testing loop, phase gates — kept inline in implement so the default execution path does not need extra reference files | implement |
-| Pattern audit | When changing a pattern, update ALL files using it | implement, reflect |
-| Mandatory deferred tracking | Create Issues (in the project's Issue tracker) for all deferred items found in reflection | reflect |
-| Trailing context syntax | Append `-- <additional context>` as the final invocation segment for skills with structured primary input | setup-project, shape, implement, reflect, address-pr-feedback |
+| Phase execution | Pre-flight, per-phase implementation/testing loop, phase gates — inline in implement; ship references `_shared/phase-execution.md` | implement, ship |
+| Pattern audit | When changing a pattern, update ALL files using it | implement, ship |
+| Mandatory deferred tracking | Create Issues (in the project's Issue tracker) for items deferred during triage | reflect, ship, address-pr-feedback |
+| Trailing context syntax | Append `-- <additional context>` as the final invocation segment for skills with structured primary input | All skills |
 | Review severity | P0-P3 (see _shared/review-rubric.md) | reflect, ship |
-| Sub-agent delegation | `context: fork` frontmatter + `(delegate)` step marker with role reference or self-contained instructions and inline fallback | shape, implement, reflect |
+| Sub-agent delegation | `(delegate)` step marker with role reference or self-contained instructions and inline fallback; `context: fork` frontmatter available when an entire skill benefits from fresh context | shape, implement, reflect, ship |
 | Review delegation | Tiny low-risk diffs stay inline; otherwise use one fresh-context reviewer by default and add a second focused pass only for high-risk or broad diffs. Consolidated in `_shared/review-delegation.md`; inline fallback executes the same lean shape sequentially | reflect, ship |
 | One question at a time | Ask convergent questions one at a time with recommended answers; do not batch (see shape/references/shaping-methodology.md) | shape |
 | Challenge then converge | Push back on terminology conflicts with CONTEXT.md, code contradictions, and vague boundaries; invent concrete scenarios to stress-test fuzzy edges | shape |
 | Vocabulary discipline | Use CONTEXT.md terms when framing questions; update CONTEXT.md inline when terms are resolved during shaping; add `_Avoid_` aliases for rejected synonyms | shape |
 | Explore before asking | Check if codebase answers each question before asking the user; provide recommended answers | shape |
 | Divergent sub-agents | `(delegate)` step with parallel sub-agents, each given radically different constraints for approach contrast; inline fallback generates sequentially (see "Writing Delegate Steps") | shape (Step 3, optional) |
-| Vertical slices | Split issues as thin end-to-end paths across all layers; classify as AFK or HITL | create-issue |
-| Reusable roles | Sub-agent personas under `roles/` — skill-specific roles co-locate with the skill; cross-skill roles live in `_shared/roles/` | implement (forge-scout), reflect + ship (forge-reviewer in _shared/) |
-| Blind research delegation | `(delegate)` research step using forge-scout role — receives questions but not the ticket; inline fallback answers factually without suggesting implementations | implement |
+| Vertical slices | Split issues as thin end-to-end paths across all layers; classify as AFK or HITL | create-issue, ship |
+| Reusable roles | Sub-agent personas under `roles/` — skill-specific roles co-locate with the skill; cross-skill roles live in `_shared/roles/` | implement + ship (forge-scout), reflect + ship via review-delegation (forge-reviewer) — both in `_shared/roles/` |
+| Blind research delegation | `(delegate)` research step using forge-scout role — receives questions but not the Issue; inline fallback answers factually without suggesting implementations | implement, ship |
 | Structure outline | High-level vertical phases with verification steps; each phase is a testable end-to-end slice | implement |
 | Durable decisions | Identify architectural decisions that survive implementation changes; keep as plan header | implement |
-| Skill composition | Composite skills reference other skills by path; orchestrators stay lean | ship |
+| Skill composition | Composite skills reuse component processes and shared `_shared/` modules; orchestrators stay lean | ship |
 | Tool-layer integration | Reference external tools (e.g., `subagent`) by name with inline fallback | ship |
 | Unattended mode | `--unattended` flag skips user interaction; plan approval auto-proceeds, triage fixes in-scope findings by default and defers only truly larger or out-of-scope items | ship, implement |
 | Issue tracker providers | Provider operations consolidated in `_shared/issue-operations.md`; skills reference it instead of inlining conditionals | create-issue, implement, reflect, ship, shape, address-pr-feedback |
diff --git a/docs/development.md b/docs/development.md
index 2dad442..4f5628f 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -35,12 +35,7 @@ No dependency installation required.
    grep -r "conventional commit" skills/
    grep -r "branch naming" skills/
    grep -r "AGENTS.md\|CLAUDE.md" skills/
-   grep -r "additional context\|-- <additional context>" \
-     skills/forge-setup-project \
-     skills/forge-shape \
-     skills/forge-implement \
-     skills/forge-reflect \
-     skills/forge-address-pr-feedback
+   grep -r "additional context\|-- <additional context>" skills/
    ```
 4. Verify cross-skill consistency: shared conventions must be identical in every skill that references them
 5. If adding or modifying a `(delegate)` step, ensure sub-agent instructions are self-contained (or composed from a role reference + task instructions) and the skill works correctly when executed inline
diff --git a/docs/testing.md b/docs/testing.md
index 4848dc0..3f363bd 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -49,18 +49,13 @@ After modifying any shared convention, grep across all relevant skills to ensure
 grep -rn "type.*scope.*description" skills/
 
 # Check workflow order
-grep -rn "forge-create-issue\|forge-implement\|forge-reflect\|forge-address-pr-feedback\|forge-setup-project" skills/
+grep -rn "forge-setup-project\|forge-shape\|forge-create-issue\|forge-implement\|forge-reflect\|forge-address-pr-feedback\|forge-ship" skills/
 
 # Check guidance file references
 grep -rn "AGENTS.md\|CLAUDE.md" skills/
 
-# Check trailing context syntax in structured-input skills
-grep -rn "additional context\|-- <additional context>" \
-  skills/forge-setup-project \
-  skills/forge-shape \
-  skills/forge-implement \
-  skills/forge-reflect \
-  skills/forge-address-pr-feedback
+# Check trailing context syntax (all skills support it)
+grep -rn "additional context\|-- <additional context>" skills/
 
 # Check all skills reference _shared/issue-operations.md (not inline conditionals)
 grep -rn "issue-operations" skills/*/SKILL.md

From 0f313b7da4a24693a4e16967279c799d09b09968 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 11:14:17 +0200
Subject: [PATCH 05/10] fix(skills): address fresh-context review findings

The review caught contradictions introduced while syncing the
consistency table (trailing-context and vertical-slices rows
over-claimed; README/AGENTS/architecture still scoped trailing
context to structured-input skills), plus pre-existing defects the
renames exposed: reflect reported before triaging, ship's Step 2
delegate lacked its Inputs/Expected blocks, and CONTEXT's Deferred
item definition didn't cover review-feedback items. Also documents
context: fork in the frontmatter conventions and compresses
three-sentence descriptions to two.

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 AGENTS.md                          |  2 +-
 CONTEXT.md                         |  6 +++---
 README.md                          |  2 +-
 docs/architecture.md               |  4 ++--
 docs/coding-guidelines.md          | 13 +++++++------
 docs/testing.md                    |  2 +-
 skills/forge-create-issue/SKILL.md |  4 ++--
 skills/forge-implement/SKILL.md    |  2 +-
 skills/forge-reflect/SKILL.md      | 12 ++++++------
 skills/forge-ship/SKILL.md         |  9 ++++++---
 10 files changed, 30 insertions(+), 26 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index f17cb09..afa590f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -35,7 +35,7 @@ gh pr list                          # list open pull requests
 3. **Never invent content** — use `<!-- TODO -->` markers rather than generating generic boilerplate
 4. **Conventional commits everywhere** — every skill enforces the same commit, branch, issue, and PR naming format
 5. **Standards first, compatibility second** — prefer `AGENTS.md` and Agent Skills conventions; keep vendor-specific compatibility lightweight
-6. **One invocation convention** — skills with structured primary input should support optional trailing execution context via `-- <additional context>` when additional guidance is useful
+6. **One invocation convention** — every skill supports optional trailing execution context via `-- <additional context>` when additional guidance is useful
 7. **Plan before code** — for complex work, research the codebase objectively and align on architecture before writing implementation; delegate research to sub-agents for unbiased findings
 8. **Mind the instruction budget** — keep skills under ~35 instructions; delegate to sub-agents when complexity grows
 
diff --git a/CONTEXT.md b/CONTEXT.md
index f1616bd..90e0eac 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -6,13 +6,13 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Issue tracker** — system tracking Issues. Providers: GitHub (default, via `gh`), markdown `plan/` folder ([spec](skills/_shared/plan-folder-spec.md)), or user-configured (declared in AGENTS.md). Detection: AGENTS.md declaration → `plan/` directory → GitHub fallback.
 
-**Issue** — one tracked unit of work. Carries title, body, and labels; the AFK/HITL mode is recorded in the body at creation.
+**Issue** — one tracked unit of work. Carries title, body, and labels; the AFK/HITL mode is recorded at creation (Issue body on GitHub, `mode` frontmatter in the markdown provider).
 
 **Plan** — structured proposal for implementing an Issue: durable decisions, vertical phases, verification steps.
 
 **Vertical slice** — end-to-end implementation crossing all layers for one narrow scenario, testable in isolation. See [vertical-slicing](skills/_shared/vertical-slicing.md).
 
-**Vertical phase** — one ordered step of a Plan: spans all affected layers, ends with tests passing and a commit. Phases sequence work within a Vertical slice.
+**Vertical phase** — one ordered step of a Plan: spans all affected layers, ends with tests passing and a commit. Each phase is itself slice-shaped — end-to-end, never a horizontal layer.
 
 **AFK / HITL** — Issue execution mode. AFK: fully specified for autonomous execution. HITL: requires human judgment during implementation. Set at creation time. See [afk-vs-hitl](skills/forge-create-issue/references/afk-vs-hitl.md).
 
@@ -22,7 +22,7 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Finding** — one issue surfaced by reflection, severity-tagged P0–P3. P3 not flagged.
 
-**Deferred item** — a Finding not addressed in the current PR; becomes a new Issue.
+**Deferred item** — a Finding or review-feedback item not addressed in the current PR; becomes a new Issue.
 
 **Composite skill** — combines other skills' processes into a single invocation (currently only `forge-ship`, composing implement and reflect).
 
diff --git a/README.md b/README.md
index 6de15fb..84b03b4 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ Forge skills follow the [Agent Skills](https://agentskills.io) open standard and
 | Address PR Feedback | `/forge-address-pr-feedback` | Address unresolved PR review comments |
 | **Ship** | **`/forge-ship <input>`** | **Implement + review in one invocation** |
 
-Skills with structured primary input also accept optional trailing execution guidance using `-- <additional context>`.
+All skills accept optional trailing execution guidance using `-- <additional context>`.
 
 ## Workflow
 
diff --git a/docs/architecture.md b/docs/architecture.md
index bee7443..5f01828 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -63,7 +63,7 @@ forge-setup-project → [forge-shape →] forge-create-issue → forge-implement
 
 See [coding-guidelines.md](coding-guidelines.md) for the complete reference: YAML frontmatter fields, section order, delegate step conventions, and role file format.
 
-Skills use **progressive disclosure**: `SKILL.md` contains core instructions, while templates and detailed reference material live in `references/` and load only when needed. Skills with structured primary input may accept `-- <additional context>` as the final segment.
+Skills use **progressive disclosure**: `SKILL.md` contains core instructions, while templates and detailed reference material live in `references/` and load only when needed. Every skill accepts `-- <additional context>` as the final segment.
 
 ## Operating Constraints
 
@@ -94,7 +94,7 @@ The instruction-budget figures (~150–200 followed reliably overall, under ~35
 | AskUserQuestion | Used for interactive skills | Structured user input with options, not free-form |
 | Pipeline linking | Each skill's "Related Skills" section | Skills reference the next step so users discover the workflow |
 | Sub-agent delegation | `(delegate)` step pattern; `context: fork` frontmatter available for whole-skill forking | Fresh context for unbiased review; `(delegate)` works across runtimes, `context: fork` is Claude Code's native whole-skill mechanism — unsuitable for skills with interactive steps |
-| Skill composition | Composite skills reference other skills by path | Keeps orchestrators lean; avoids duplicating step-level instructions across skills |
+| Skill composition | Composite skills reuse component processes and shared `_shared/` modules | Keeps orchestrators lean; shared modules prevent duplicated step-level instructions from drifting |
 | Tool-layer integration | Skills reference external tools by name, not by import | Runtimes and extensions expose delegation/model-selection capabilities; skills use them when available and fall back when not — zero coupling. Runtime-specific agent files or presets are optional local tuning, not part of Forge. When a runtime couples agent names to model/provider selection, push role content, prefer inheriting the parent session configuration over hard-coded agent IDs, use cheap fast models for factual scouting, and prefer cheaper review-capable models for routine review work |
 | Reusable roles | Skill-specific: `<skill>/roles/*.md`; cross-skill: `_shared/roles/*.md` | Delegation personas separated from skill body; single-use roles co-locate with the skill, shared roles live in `_shared/` |
 | Blind research delegation | Scout researches codebase without seeing the Issue | Knowing the goal causes opinions to leak into research — objective facts lead to better planning |
diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 094b940..9b80144 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -22,6 +22,7 @@ Every skill follows the same section order:
 - `description`: one or two sentences describing what the skill does and when to use it. This text is what compatible agents use for skill discovery, so it must be descriptive.
 - `disable-model-invocation`: set to `true` for skills that should only be invoked by the user via slash command (workflow entry points). Omit or set to `false` for skills that agents may auto-activate.
 - `allowed-tools`: comma-separated list of tools the skill may use. Omit to allow all tools.
+- `context: fork`: forks the entire skill into a sub-agent on runtimes that support it. Only for skills with no interactive steps; currently no forge skill sets it.
 
 ## Writing Process Steps
 
@@ -56,12 +57,12 @@ When a delegation step benefits from a separated persona, extract it into a **ro
 ```markdown
 #### Research (delegate)
 
-Delegate to a [forge-scout](roles/forge-scout.md) sub-agent that receives only
+Delegate to a [forge-scout](../_shared/roles/forge-scout.md) sub-agent that receives only
 the questions. If the runtime does not support sub-agents, read the role
 file and answer each question following its rules.
 
 **Inputs provided to sub-agent:**
-- Role: [forge-scout](roles/forge-scout.md)
+- Role: [forge-scout](../_shared/roles/forge-scout.md)
 - The research questions
 
 **Expected output:** One factual answer per question.
@@ -108,9 +109,9 @@ Conventions shared across skills. When modifying any, update every skill that re
 | Canonical guidance file | `AGENTS.md` canonical; `CLAUDE.md` compatibility symlink | setup-project, implement, ship |
 | Validate approach | Present plan and get user confirmation before implementing (skipped in unattended mode) | implement, ship |
 | Phase execution | Pre-flight, per-phase implementation/testing loop, phase gates — inline in implement; ship references `_shared/phase-execution.md` | implement, ship |
-| Pattern audit | When changing a pattern, update ALL files using it | implement, ship |
-| Mandatory deferred tracking | Create Issues (in the project's Issue tracker) for items deferred during triage | reflect, ship, address-pr-feedback |
-| Trailing context syntax | Append `-- <additional context>` as the final invocation segment for skills with structured primary input | All skills |
+| Pattern audit | When changing a pattern, update ALL files using it | implement, ship, reflect |
+| Mandatory deferred tracking | Create Issues (in the project's Issue tracker) for every Deferred item | reflect, ship, address-pr-feedback |
+| Trailing context syntax | Append `-- <additional context>` as the final invocation segment | All skills |
 | Review severity | P0-P3 (see _shared/review-rubric.md) | reflect, ship |
 | Sub-agent delegation | `(delegate)` step marker with role reference or self-contained instructions and inline fallback; `context: fork` frontmatter available when an entire skill benefits from fresh context | shape, implement, reflect, ship |
 | Review delegation | Tiny low-risk diffs stay inline; otherwise use one fresh-context reviewer by default and add a second focused pass only for high-risk or broad diffs. Consolidated in `_shared/review-delegation.md`; inline fallback executes the same lean shape sequentially | reflect, ship |
@@ -119,7 +120,7 @@ Conventions shared across skills. When modifying any, update every skill that re
 | Vocabulary discipline | Use CONTEXT.md terms when framing questions; update CONTEXT.md inline when terms are resolved during shaping; add `_Avoid_` aliases for rejected synonyms | shape |
 | Explore before asking | Check if codebase answers each question before asking the user; provide recommended answers | shape |
 | Divergent sub-agents | `(delegate)` step with parallel sub-agents, each given radically different constraints for approach contrast; inline fallback generates sequentially (see "Writing Delegate Steps") | shape (Step 3, optional) |
-| Vertical slices | Split issues as thin end-to-end paths across all layers; classify as AFK or HITL | create-issue, ship |
+| Vertical slices | Split issues as thin end-to-end paths across all layers; classify as AFK or HITL | create-issue |
 | Reusable roles | Sub-agent personas under `roles/` — skill-specific roles co-locate with the skill; cross-skill roles live in `_shared/roles/` | implement + ship (forge-scout), reflect + ship via review-delegation (forge-reviewer) — both in `_shared/roles/` |
 | Blind research delegation | `(delegate)` research step using forge-scout role — receives questions but not the Issue; inline fallback answers factually without suggesting implementations | implement, ship |
 | Structure outline | High-level vertical phases with verification steps; each phase is a testable end-to-end slice | implement |
diff --git a/docs/testing.md b/docs/testing.md
index 3f363bd..29f6aba 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -57,6 +57,6 @@ grep -rn "AGENTS.md\|CLAUDE.md" skills/
 # Check trailing context syntax (all skills support it)
 grep -rn "additional context\|-- <additional context>" skills/
 
-# Check all skills reference _shared/issue-operations.md (not inline conditionals)
+# Check Issue-touching skills reference _shared/issue-operations.md (not inline conditionals; setup-project has none)
 grep -rn "issue-operations" skills/*/SKILL.md
 ```
diff --git a/skills/forge-create-issue/SKILL.md b/skills/forge-create-issue/SKILL.md
index 99599f4..c35520c 100644
--- a/skills/forge-create-issue/SKILL.md
+++ b/skills/forge-create-issue/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: forge-create-issue
-description: Collaboratively plan and create well-structured Issues through interactive discussion. Use when the user wants to create an Issue, report a bug, or scope out work that is already understood — use forge-shape first when the idea is still vague. Supports GitHub, markdown plan/ folder, and other providers.
+description: Collaboratively plan and create well-structured Issues through interactive discussion (GitHub, markdown plan/ folder, or other providers). Use when the user wants to create an Issue, report a bug, or scope out work that is already understood — use forge-shape first when the idea is still vague.
 disable-model-invocation: true
 allowed-tools: Read, Edit, Write, Bash, Grep, Glob, WebSearch, AskUserQuestion
 ---
@@ -74,7 +74,7 @@ If splitting makes sense, offer: single Issue, multiple linked Issues, or epic w
 ## Summary
 [1-2 sentences]
 
-**Execution mode:** [AFK | HITL]
+**Execution mode:** [AFK | HITL] <!-- markdown provider: use the `mode` frontmatter field instead -->
 
 ## Problem / Motivation
 [Why this needs to exist]
diff --git a/skills/forge-implement/SKILL.md b/skills/forge-implement/SKILL.md
index e76bfce..433a847 100644
--- a/skills/forge-implement/SKILL.md
+++ b/skills/forge-implement/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: forge-implement
-description: Implement a feature or fix from an Issue, plan file, or free-text description, following project standards. Use when the user wants to start working on an Issue, implement a feature, or fix a bug. Stops after opening the PR — use forge-ship to also run review.
+description: Implement a feature or fix from an Issue, plan file, or free-text description, following project standards. Use when the user wants to start working on an Issue, implement a feature, or fix a bug — stops after opening the PR (use forge-ship to also run review).
 disable-model-invocation: true
 ---
 
diff --git a/skills/forge-reflect/SKILL.md b/skills/forge-reflect/SKILL.md
index e8acade..9055ada 100644
--- a/skills/forge-reflect/SKILL.md
+++ b/skills/forge-reflect/SKILL.md
@@ -62,13 +62,9 @@ Follow the [review-delegation](../_shared/review-delegation.md) process: collect
 
 ### Step 3: Run Quality Gates
 
-Run the project's lint, format, type check, and test commands. Fix issues and commit fixes.
+Run the project's lint, format, type check, and test commands (and coverage where configured). Fix issues and commit fixes.
 
-### Step 4: Report
-
-Aggregate findings from all review passes (Step 2) with quality gate results (Step 3) into the summary format below. Deduplicate any findings flagged by multiple passes — keep the highest severity.
-
-### Step 5: Triage Findings
+### Step 4: Triage Findings
 
 Present each Finding to the user via AskUserQuestion and ask whether to **fix now** or **defer**.
 
@@ -82,6 +78,10 @@ State your recommendation and let the user decide. Then:
 - **Fix now:** apply the fix and commit it
 - **Deferred items:** create an Issue in the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)) with context and proposed solution
 
+### Step 5: Report
+
+Aggregate findings from all review passes (Step 2), quality gate results (Step 3), and triage outcomes (Step 4) into the summary format below. Deduplicate any findings flagged by multiple passes — keep the highest severity.
+
 ## Output Format
 
 ```text
diff --git a/skills/forge-ship/SKILL.md b/skills/forge-ship/SKILL.md
index 477a8f0..5c6c285 100644
--- a/skills/forge-ship/SKILL.md
+++ b/skills/forge-ship/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: forge-ship
-description: End-to-end implementation and self-review in a single invocation. Implements from an Issue, plan file, or free-text description, then runs a lean fresh-context review. Use when the user wants to implement and review without manual handoff between skills.
+description: End-to-end implementation and self-review in a single invocation — implements from an Issue, plan file, or free-text description, then runs a lean fresh-context review. Use when the user wants to implement and review without manual handoff between skills.
 disable-model-invocation: true
 ---
 
@@ -22,7 +22,7 @@ Same as `forge-implement` (`$ARGUMENTS`): Issue number/URL, plan file path, or f
 
 Determine input type (Issue number/URL, plan file, or free-text). For Issues, fetch via the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Parse requirements and acceptance criteria. Flag if underspecified.
 
-#### 1b. Plan
+#### 1b. Plan (delegate)
 
 For complex work, write 3–7 research questions and delegate to a sub-agent with the [forge-scout](../_shared/roles/forge-scout.md) role for unbiased codebase research. Prefer a cheap fast model for scout work. If the runtime does not support sub-agents, read the role file and answer the questions inline following its rules.
 
@@ -70,7 +70,7 @@ git push -u origin <BRANCH_NAME>
 gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body "<PR_BODY>"
 ```
 
-Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: changes list, test plan, quality checklist. Close the Issue when one exists. Add a `> [!WARNING]` block for manual deployment steps.
+The PR title uses conventional commit format. Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: changes list, test plan, quality checklist. Close the Issue when one exists. Add a `> [!WARNING]` block for manual deployment steps.
 
 Do not produce the implementation summary yet — the review will inform the final report.
 
@@ -78,6 +78,9 @@ Do not produce the implementation summary yet — the review will inform the fin
 
 Follow the [review-delegation](../_shared/review-delegation.md) process: collect the diff from the implementation, prefer one inline review pass for tiny low-risk diffs, otherwise use one fresh-context review pass by default, add a second pass only when risk justifies it, and aggregate findings. Fresh context eliminates self-review bias when delegated review is used — reviewers have no memory of implementation decisions.
 
+**Inputs provided to sub-agent:** the branch diff, changed file list, and project conventions per review-delegation.
+**Expected output:** Deduplicated findings grouped by file with severity tags (P0/P1/P2).
+
 ### Step 3: Triage Findings
 
 Use the aggregated findings from the review delegation.

From 0f26ad7cd5204ca02d237b118ba83f4f713572d0 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 16:19:23 +0200
Subject: [PATCH 06/10] fix(review): make tiny-diff inline review conditional
 on authorship
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Removing context: fork from forge-reflect meant inline tiny-diff
reviews run in the session that may have just written the code —
the fork previously gave even those fresh eyes. Rather than always
delegating (which would erase the lean-review design), the inline
path is now allowed only when the reviewing session did not author
the changes. For forge-ship the session always authors the diff, so
its review now always delegates.

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 CONTEXT.md                          | 2 +-
 README.md                           | 2 +-
 docs/architecture.md                | 8 ++++----
 docs/coding-guidelines.md           | 4 ++--
 skills/_shared/review-delegation.md | 2 +-
 skills/forge-reflect/SKILL.md       | 2 +-
 skills/forge-ship/SKILL.md          | 6 +++---
 7 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/CONTEXT.md b/CONTEXT.md
index 90e0eac..c6955b3 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -18,7 +18,7 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Reflection** — self-review of current changes before peer review: tiny diffs review inline, otherwise one fresh-context review pass by default, deepened only when risk justifies it. Produces Findings.
 
-**Tiny diff** — roughly ≤2 files and ≤100 changed lines with low risk; reviewed inline without delegation. See [review-delegation](skills/_shared/review-delegation.md).
+**Tiny diff** — roughly ≤2 files and ≤100 changed lines with low risk; reviewed inline only when the session didn't author the changes. See [review-delegation](skills/_shared/review-delegation.md).
 
 **Finding** — one issue surfaced by reflection, severity-tagged P0–P3. P3 not flagged.
 
diff --git a/README.md b/README.md
index 84b03b4..12b876a 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@ forge-setup-project → [forge-shape →] forge-create-issue → forge-implement
                                                                         ╰──── forge-ship ────╯
 ```
 
-`forge-ship` composes implement + review into a single invocation. Review stays lean by default — tiny low-risk diffs stay inline; otherwise use one fresh-context reviewer, with a second pass only when risk justifies it. Scout and review work should use cheaper models when the runtime supports per-task model choice; otherwise they should inherit the parent session model cleanly.
+`forge-ship` composes implement + review into a single invocation. Review stays lean by default — tiny low-risk diffs stay inline when the session didn't author them; otherwise use one fresh-context reviewer, with a second pass only when risk justifies it. Scout and review work should use cheaper models when the runtime supports per-task model choice; otherwise they should inherit the parent session model cleanly.
 
 ## Install
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 5f01828..74d07f7 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -49,15 +49,15 @@ forge-setup-project → [forge-shape →] forge-create-issue → forge-implement
 
 `forge-shape` is optional — use it when the idea is vague and needs convergent questioning to specify before issue creation.
 
-`forge-ship` is a **composite skill** — it composes implement and reflect into a single invocation, keeping review lean with inline review for tiny low-risk diffs and one fresh-context reviewer by default otherwise.
+`forge-ship` is a **composite skill** — it composes implement and reflect into a single invocation, keeping review lean with one fresh-context reviewer by default (its session authors the diff, so review always delegates).
 
 - **forge-setup-project** sets up or audits a project's context infrastructure using a three-tier model: `AGENTS.md` as lean hot memory, `docs/` as earned warm memory, and `specs/` (or equivalent) as cold memory, with signal-to-noise scoring for existing guidance. It also supports migrating legacy `CLAUDE.md`-first repos to an `AGENTS.md`-first layout.
 - **forge-shape** investigates the codebase, shapes the problem through one-at-a-time questioning — challenging terminology against CONTEXT.md, cross-referencing claims against code, stress-testing with concrete scenarios — until a shared design concept emerges. Updates CONTEXT.md inline as terms are resolved. Optionally explores contrasting approaches if shaping didn't surface one, and produces a plan summary ready for issue creation
 - **forge-create-issue** uses AskUserQuestion to collaboratively scope work, then creates Issues in the project's Issue tracker (GitHub, markdown `plan/` folder, or user-configured provider)
 - **forge-implement** reads an issue, plan file, or free-text description, researches the codebase (optionally via blind scout delegation for complex work), plans vertical implementation phases using inline guidance, and opens a PR
-- **forge-reflect** self-reviews changes (PR, branch diff, or uncommitted) inline for tiny low-risk diffs, otherwise using one fresh-context reviewer by default and adding a second focused pass only for high-risk or broad diffs, with a P0-P3 severity rubric
+- **forge-reflect** self-reviews changes (PR, branch diff, or uncommitted) inline for tiny low-risk diffs the session didn't author, otherwise using one fresh-context reviewer by default and adding a second focused pass only for high-risk or broad diffs, with a P0-P3 severity rubric
 - **forge-address-pr-feedback** fetches unresolved review threads via GraphQL and addresses each one
-- **forge-ship** composes implement and reflect — implementation runs inline, review stays inline for tiny low-risk diffs and otherwise uses one fresh-context reviewer by default, findings are triaged with the user
+- **forge-ship** composes implement and reflect — implementation runs inline, review always delegates to one fresh-context reviewer by default (the session authored the diff), findings are triaged with the user
 
 ## Skill & Role File Format
 
@@ -74,7 +74,7 @@ Practitioners call the workable region the **smart zone** and the degraded regio
 | Mechanism | How it responds |
 |-----------|-----------------|
 | Sub-agent delegation (`(delegate)` steps) | Move work into fresh context windows when the parent is approaching the dumb zone |
-| Fresh-context review (`forge-reflect`, `forge-ship`) | Tiny low-risk diffs can stay inline; otherwise one reviewer starts in smart zone by default, and depth is added only when risk justifies it |
+| Fresh-context review (`forge-reflect`, `forge-ship`) | Tiny low-risk diffs stay inline only when the session didn't author them; otherwise one reviewer starts in smart zone by default, and depth is added only when risk justifies it |
 | Progressive disclosure (`references/`) | Load companion philosophy on demand instead of always-loading every skill's full content |
 | Three-tier context model (`AGENTS.md` / `docs/` / specs) | Each tier earns its always-loaded cost; cold tier loads only when needed |
 | Instruction budget (under ~35 instructions per skill body) | Skills stay lean enough to compose without exceeding the ~150–200 instructions frontier LLMs follow consistently |
diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 9b80144..47b1c0f 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -114,7 +114,7 @@ Conventions shared across skills. When modifying any, update every skill that re
 | Trailing context syntax | Append `-- <additional context>` as the final invocation segment | All skills |
 | Review severity | P0-P3 (see _shared/review-rubric.md) | reflect, ship |
 | Sub-agent delegation | `(delegate)` step marker with role reference or self-contained instructions and inline fallback; `context: fork` frontmatter available when an entire skill benefits from fresh context | shape, implement, reflect, ship |
-| Review delegation | Tiny low-risk diffs stay inline; otherwise use one fresh-context reviewer by default and add a second focused pass only for high-risk or broad diffs. Consolidated in `_shared/review-delegation.md`; inline fallback executes the same lean shape sequentially | reflect, ship |
+| Review delegation | Tiny low-risk diffs stay inline when the session didn't author them; otherwise use one fresh-context reviewer by default and add a second focused pass only for high-risk or broad diffs. Consolidated in `_shared/review-delegation.md`; inline fallback executes the same lean shape sequentially | reflect, ship |
 | One question at a time | Ask convergent questions one at a time with recommended answers; do not batch (see shape/references/shaping-methodology.md) | shape |
 | Challenge then converge | Push back on terminology conflicts with CONTEXT.md, code contradictions, and vague boundaries; invent concrete scenarios to stress-test fuzzy edges | shape |
 | Vocabulary discipline | Use CONTEXT.md terms when framing questions; update CONTEXT.md inline when terms are resolved during shaping; add `_Avoid_` aliases for rejected synonyms | shape |
@@ -137,7 +137,7 @@ Frontier LLMs follow ~150-200 instructions with good consistency. Beyond that, a
 
 - **Target: under 35 distinct instructions per skill.** Count each directive, conditional, and behavioral rule.
 - **Delegate when growing past the budget.** Use sub-agent delegation to offload self-contained concerns (research, review, approach generation) into fresh context windows.
-- **Prefer the minimum effective reviewer count.** For review, keep tiny low-risk diffs inline, otherwise start with one focused fresh-context reviewer and deepen only when risk clearly justifies another pass.
+- **Prefer the minimum effective reviewer count.** For review, keep tiny low-risk diffs inline when the session didn't author them, otherwise start with one focused fresh-context reviewer and deepen only when risk clearly justifies another pass.
 - **Match model cost to task shape.** Factual scouting should use cheap fast models when the runtime supports per-task model choice; routine review should prefer cheaper review-capable models; save the strongest models for synthesis, planning, and hard implementation decisions. If the runtime cannot vary models per task, the skill should still work by inheriting the parent session model.
 - **Don't use prompts for control flow.** If a skill has multi-way branching (mode selection, input type routing), split into focused skills or use a lightweight routing step.
 
diff --git a/skills/_shared/review-delegation.md b/skills/_shared/review-delegation.md
index a8d6a4a..9c87570 100644
--- a/skills/_shared/review-delegation.md
+++ b/skills/_shared/review-delegation.md
@@ -19,7 +19,7 @@ Before reviewing, collect:
 
 Use the smallest review shape that still gives trustworthy signal:
 
-1. **Tiny diff: inline review** — only if the change is small and low-risk (roughly `<=2` files and `<=100` changed lines), with **no** risky signals such as auth/authz, secrets, payments, migrations, concurrency, jobs, caches, public API/protocol changes, or infrastructure/config changes. Review inline in the current context using the default combined checklist.
+1. **Tiny diff: inline review** — only if the change is small and low-risk (roughly `<=2` files and `<=100` changed lines), with **no** risky signals such as auth/authz, secrets, payments, migrations, concurrency, jobs, caches, public API/protocol changes, or infrastructure/config changes, **and the current session did not implement the changes**. A session reviewing its own diff has self-review bias — delegate even tiny diffs then. Review inline in the current context using the default combined checklist.
 2. **Default: one reviewer** — for everything else, use one fresh-context reviewer running the combined checklist.
 3. **Mandatory second reviewer for risky changes** — add a second focused pass whenever the diff touches:
    - auth, authorization, secrets, payments, or other security-sensitive code
diff --git a/skills/forge-reflect/SKILL.md b/skills/forge-reflect/SKILL.md
index 9055ada..9478734 100644
--- a/skills/forge-reflect/SKILL.md
+++ b/skills/forge-reflect/SKILL.md
@@ -110,7 +110,7 @@ Aggregate findings from all review passes (Step 2), quality gate results (Step 3
 ## Guidelines
 
 - **Pattern consistency is the highest-value check**
-- **Tiny low-risk diffs stay inline** — avoid fresh-context overhead when the change is obviously small
+- **Tiny low-risk diffs stay inline** — avoid fresh-context overhead when the change is obviously small and this session didn't author it
 - **Keep review lean** — one reviewer by default, second only when risk justifies it
 - **Skip noise** — see [review rubric](../_shared/review-rubric.md)
 - **Bias toward fixing in the same PR** — only create Issues for confirmed deferrals that are truly larger or out of scope
diff --git a/skills/forge-ship/SKILL.md b/skills/forge-ship/SKILL.md
index 5c6c285..b789e04 100644
--- a/skills/forge-ship/SKILL.md
+++ b/skills/forge-ship/SKILL.md
@@ -6,7 +6,7 @@ disable-model-invocation: true
 
 # Ship a Change
 
-Implement end to end — code it, review it, ship it. Implementation runs in the current session; tiny low-risk diffs review inline, otherwise review uses one fresh-context reviewer by default and deepens only when risk justifies it.
+Implement end to end — code it, review it, ship it. Implementation runs in the current session; review always delegates to fresh context — this session authored the diff, so even tiny diffs get an unbiased reviewer — and deepens only when risk justifies it.
 
 ## Input
 
@@ -76,7 +76,7 @@ Do not produce the implementation summary yet — the review will inform the fin
 
 ### Step 2: Review (delegate)
 
-Follow the [review-delegation](../_shared/review-delegation.md) process: collect the diff from the implementation, prefer one inline review pass for tiny low-risk diffs, otherwise use one fresh-context review pass by default, add a second pass only when risk justifies it, and aggregate findings. Fresh context eliminates self-review bias when delegated review is used — reviewers have no memory of implementation decisions.
+Follow the [review-delegation](../_shared/review-delegation.md) process: collect the diff from the implementation, use one fresh-context review pass by default (this session authored the diff, so the inline tiny-diff path never applies), add a second pass only when risk justifies it, and aggregate findings. Fresh context eliminates self-review bias when delegated review is used — reviewers have no memory of implementation decisions.
 
 **Inputs provided to sub-agent:** the branch diff, changed file list, and project conventions per review-delegation.
 **Expected output:** Deduplicated findings grouped by file with severity tags (P0/P1/P2).
@@ -130,7 +130,7 @@ Report implementation and review results together.
 
 ## Guidelines
 
-- **Tiny low-risk diffs stay inline** — do not pay sub-agent overhead when the change is obviously small
+- **Even tiny diffs delegate here** — this session authored the changes, so inline review would be self-review
 - **Delegated review runs in fresh context** — reviewers have no implementation memory
 - **Keep review lean** — one reviewer by default, second only when risk justifies it
 - **Don't skip the review** — even if implementation felt clean

From 34193bf8d01a3a89ee6b4ceadf4d042cc9ef35da Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Mon, 27 Jul 2026 17:08:17 +0200
Subject: [PATCH 07/10] refactor(skills): rightsize skill suite per Claude 5
 context rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Applies the current context-engineering guidance for Claude 5 models:
prefer judgment over defensive rules, never state the same guidance in
two places, and use progressive disclosure for detail.

- ship: Step 1 now executes forge-implement's process by reference
  instead of paraphrasing it as 1a-1g — the duplication had already
  drifted once; ship's own body drops to ~20 instructions (note: a
  ship invocation still loads implement's ~35, so the budget is
  honest per file, not per invocation — recorded in coding-guidelines)
- implement: references _shared/phase-execution.md, pattern-audit.md,
  and deep-modules.md instead of inlining copies; defensive flag-lists
  become judgment calls with an unattended fallback
- setup-project: three-way mode table collapses into one assessment
  step (file state determines the work); interrogation lists compress
  to intent; scoring rubric and tier model stay as the skill's opinion
- shape/create-issue/reflect: guidelines restating process steps or
  shared modules deleted; the authoritative statement survives in one
  place
- post-review fixes: implement's clarification step is unattended-
  aware so ship --unattended cannot block; pr-workflow.md content spec
  restored; output-format headings match the collapsed flow; the
  lettered-sub-step rule that invited re-inlining removed; ship's
  composition described consistently everywhere

Claude-Session: https://claude.ai/code/session_0187yZ3Nnp45s9BVYxnpJ7Ca
---
 AGENTS.md                                     |  2 +-
 CONTEXT.md                                    |  2 +-
 README.md                                     |  2 +-
 docs/architecture.md                          |  6 +-
 docs/coding-guidelines.md                     | 14 ++--
 skills/forge-create-issue/SKILL.md            |  2 -
 skills/forge-implement/SKILL.md               | 28 ++-----
 skills/forge-reflect/SKILL.md                 |  4 -
 skills/forge-setup-project/SKILL.md           | 81 ++++---------------
 .../references/output-format.md               |  6 +-
 skills/forge-shape/SKILL.md                   |  5 --
 skills/forge-ship/SKILL.md                    | 80 ++----------------
 12 files changed, 44 insertions(+), 188 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index afa590f..68a37cb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -36,7 +36,7 @@ gh pr list                          # list open pull requests
 4. **Conventional commits everywhere** — every skill enforces the same commit, branch, issue, and PR naming format
 5. **Standards first, compatibility second** — prefer `AGENTS.md` and Agent Skills conventions; keep vendor-specific compatibility lightweight
 6. **One invocation convention** — every skill supports optional trailing execution context via `-- <additional context>` when additional guidance is useful
-7. **Plan before code** — for complex work, research the codebase objectively and align on architecture before writing implementation; delegate research to sub-agents for unbiased findings
+7. **Plan before code** — for complex work, research the codebase objectively and align on architecture before writing implementation; delegate research to sub-agents for unbiased answers
 8. **Mind the instruction budget** — keep skills under ~35 instructions; delegate to sub-agents when complexity grows
 
 ## Commits
diff --git a/CONTEXT.md b/CONTEXT.md
index c6955b3..fe25214 100644
--- a/CONTEXT.md
+++ b/CONTEXT.md
@@ -24,7 +24,7 @@ Shared vocabulary used across multiple skills. Terms used in only one skill stay
 
 **Deferred item** — a Finding or review-feedback item not addressed in the current PR; becomes a new Issue.
 
-**Composite skill** — combines other skills' processes into a single invocation (currently only `forge-ship`, composing implement and reflect).
+**Composite skill** — combines other skills' processes into a single invocation (currently only `forge-ship`, composing implement with the review flow shared with reflect).
 
 **Inline fallback** — `(delegate)` step provides both sub-agent and in-context paths for runtime portability.
 
diff --git a/README.md b/README.md
index 12b876a..c4b6acf 100644
--- a/README.md
+++ b/README.md
@@ -43,7 +43,7 @@ forge-setup-project → [forge-shape →] forge-create-issue → forge-implement
                                                                         ╰──── forge-ship ────╯
 ```
 
-`forge-ship` composes implement + review into a single invocation. Review stays lean by default — tiny low-risk diffs stay inline when the session didn't author them; otherwise use one fresh-context reviewer, with a second pass only when risk justifies it. Scout and review work should use cheaper models when the runtime supports per-task model choice; otherwise they should inherit the parent session model cleanly.
+`forge-ship` composes implement + review into a single invocation; its review always delegates to a fresh-context reviewer (the session authored the diff), adding a second pass only when risk justifies it. Standalone `forge-reflect` keeps tiny diffs inline when the session didn't author them. Scout and review work should use cheaper models when the runtime supports per-task model choice; otherwise they should inherit the parent session model cleanly.
 
 ## Install
 
diff --git a/docs/architecture.md b/docs/architecture.md
index 74d07f7..abdd541 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -49,15 +49,15 @@ forge-setup-project → [forge-shape →] forge-create-issue → forge-implement
 
 `forge-shape` is optional — use it when the idea is vague and needs convergent questioning to specify before issue creation.
 
-`forge-ship` is a **composite skill** — it composes implement and reflect into a single invocation, keeping review lean with one fresh-context reviewer by default (its session authors the diff, so review always delegates).
+`forge-ship` is a **composite skill** — it executes implement's process and the review flow shared with reflect in a single invocation, with one fresh-context reviewer by default (its session authors the diff, so review always delegates).
 
 - **forge-setup-project** sets up or audits a project's context infrastructure using a three-tier model: `AGENTS.md` as lean hot memory, `docs/` as earned warm memory, and `specs/` (or equivalent) as cold memory, with signal-to-noise scoring for existing guidance. It also supports migrating legacy `CLAUDE.md`-first repos to an `AGENTS.md`-first layout.
 - **forge-shape** investigates the codebase, shapes the problem through one-at-a-time questioning — challenging terminology against CONTEXT.md, cross-referencing claims against code, stress-testing with concrete scenarios — until a shared design concept emerges. Updates CONTEXT.md inline as terms are resolved. Optionally explores contrasting approaches if shaping didn't surface one, and produces a plan summary ready for issue creation
 - **forge-create-issue** uses AskUserQuestion to collaboratively scope work, then creates Issues in the project's Issue tracker (GitHub, markdown `plan/` folder, or user-configured provider)
-- **forge-implement** reads an issue, plan file, or free-text description, researches the codebase (optionally via blind scout delegation for complex work), plans vertical implementation phases using inline guidance, and opens a PR
+- **forge-implement** reads an Issue, plan file, or free-text description, researches the codebase (optionally via blind scout delegation for complex work), plans vertical implementation phases following `_shared/phase-execution.md`, and opens a PR
 - **forge-reflect** self-reviews changes (PR, branch diff, or uncommitted) inline for tiny low-risk diffs the session didn't author, otherwise using one fresh-context reviewer by default and adding a second focused pass only for high-risk or broad diffs, with a P0-P3 severity rubric
 - **forge-address-pr-feedback** fetches unresolved review threads via GraphQL and addresses each one
-- **forge-ship** composes implement and reflect — implementation runs inline, review always delegates to one fresh-context reviewer by default (the session authored the diff), findings are triaged with the user
+- **forge-ship** executes forge-implement's process, then delegates review to one fresh-context reviewer by default (the session authored the diff) and triages findings with the user
 
 ## Skill & Role File Format
 
diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 47b1c0f..36cbaf9 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -30,7 +30,6 @@ Every skill follows the same section order:
 - Include bash examples for any CLI operations (especially `gh` and `git` commands)
 - Use `AskUserQuestion` for user decisions — never assume
 - Steps should be numbered sequentially and named with action verbs: "Create", "Fetch", "Analyze", "Generate"
-- Composite skills may subdivide a wrapping step into lettered sub-steps (`#### 1a. <Action>`) when inlining a component skill's flow
 
 ## Writing Delegate Steps
 
@@ -105,11 +104,11 @@ Conventions shared across skills. When modifying any, update every skill that re
 
 | Convention | Format | Referenced In |
 |------------|--------|---------------|
-| Conventional commits | `<type>(<scope>): <description>` — titles, branches, commits, PRs | create-issue, shape, implement, ship, address-pr-feedback |
-| Canonical guidance file | `AGENTS.md` canonical; `CLAUDE.md` compatibility symlink | setup-project, implement, ship |
+| Conventional commits | `<type>(<scope>): <description>` — titles, branches, commits, PRs | create-issue, shape, implement, address-pr-feedback |
+| Canonical guidance file | `AGENTS.md` canonical; `CLAUDE.md` compatibility symlink | setup-project, implement |
 | Validate approach | Present plan and get user confirmation before implementing (skipped in unattended mode) | implement, ship |
-| Phase execution | Pre-flight, per-phase implementation/testing loop, phase gates — inline in implement; ship references `_shared/phase-execution.md` | implement, ship |
-| Pattern audit | When changing a pattern, update ALL files using it | implement, ship, reflect |
+| Phase execution | Pre-flight, per-phase implementation/testing loop, phase gates — consolidated in `_shared/phase-execution.md` | implement |
+| Pattern audit | When changing a pattern, update ALL files using it — consolidated in `_shared/pattern-audit.md` | implement, reflect |
 | Mandatory deferred tracking | Create Issues (in the project's Issue tracker) for every Deferred item | reflect, ship, address-pr-feedback |
 | Trailing context syntax | Append `-- <additional context>` as the final invocation segment | All skills |
 | Review severity | P0-P3 (see _shared/review-rubric.md) | reflect, ship |
@@ -121,8 +120,8 @@ Conventions shared across skills. When modifying any, update every skill that re
 | Explore before asking | Check if codebase answers each question before asking the user; provide recommended answers | shape |
 | Divergent sub-agents | `(delegate)` step with parallel sub-agents, each given radically different constraints for approach contrast; inline fallback generates sequentially (see "Writing Delegate Steps") | shape (Step 3, optional) |
 | Vertical slices | Split issues as thin end-to-end paths across all layers; classify as AFK or HITL | create-issue |
-| Reusable roles | Sub-agent personas under `roles/` — skill-specific roles co-locate with the skill; cross-skill roles live in `_shared/roles/` | implement + ship (forge-scout), reflect + ship via review-delegation (forge-reviewer) — both in `_shared/roles/` |
-| Blind research delegation | `(delegate)` research step using forge-scout role — receives questions but not the Issue; inline fallback answers factually without suggesting implementations | implement, ship |
+| Reusable roles | Sub-agent personas under `roles/` — skill-specific roles co-locate with the skill; cross-skill roles live in `_shared/roles/` | implement (forge-scout), reflect + ship via review-delegation (forge-reviewer) — both in `_shared/roles/` |
+| Blind research delegation | `(delegate)` research step using forge-scout role — receives questions but not the Issue; inline fallback answers factually without suggesting implementations | implement |
 | Structure outline | High-level vertical phases with verification steps; each phase is a testable end-to-end slice | implement |
 | Durable decisions | Identify architectural decisions that survive implementation changes; keep as plan header | implement |
 | Skill composition | Composite skills reuse component processes and shared `_shared/` modules; orchestrators stay lean | ship |
@@ -137,6 +136,7 @@ Frontier LLMs follow ~150-200 instructions with good consistency. Beyond that, a
 
 - **Target: under 35 distinct instructions per skill.** Count each directive, conditional, and behavioral rule.
 - **Delegate when growing past the budget.** Use sub-agent delegation to offload self-contained concerns (research, review, approach generation) into fresh context windows.
+- **Count composites per invocation.** A composite skill loads its component's instructions too — keep the composite's own body thin so the combined load stays reasonable.
 - **Prefer the minimum effective reviewer count.** For review, keep tiny low-risk diffs inline when the session didn't author them, otherwise start with one focused fresh-context reviewer and deepen only when risk clearly justifies another pass.
 - **Match model cost to task shape.** Factual scouting should use cheap fast models when the runtime supports per-task model choice; routine review should prefer cheaper review-capable models; save the strongest models for synthesis, planning, and hard implementation decisions. If the runtime cannot vary models per task, the skill should still work by inheriting the parent session model.
 - **Don't use prompts for control flow.** If a skill has multi-way branching (mode selection, input type routing), split into focused skills or use a lightweight routing step.
diff --git a/skills/forge-create-issue/SKILL.md b/skills/forge-create-issue/SKILL.md
index c35520c..33a02dc 100644
--- a/skills/forge-create-issue/SKILL.md
+++ b/skills/forge-create-issue/SKILL.md
@@ -103,8 +103,6 @@ Share the Issue reference. Suggest using `forge-implement` to start implementati
 ## Guidelines
 
 - **Be curious** — challenge assumptions, ask "why" and "what if"
-- **Explore first** — always research the codebase before proposing solutions
-- **Never skip alternatives** — even if one approach seems obvious
 - **Don't over-specify** — leave room for implementer judgment
 - **No time estimates**
 
diff --git a/skills/forge-implement/SKILL.md b/skills/forge-implement/SKILL.md
index 433a847..567f315 100644
--- a/skills/forge-implement/SKILL.md
+++ b/skills/forge-implement/SKILL.md
@@ -24,11 +24,11 @@ Determine the input type and extract requirements. Detect the Issue tracker prov
 - **Plan file** — extract goals, requirements, constraints, acceptance criteria.
 - **Free-text** — parse scope and constraints. Ask clarifying questions if underspecified.
 
-Flag for user input if: vague criteria, `discovery` label, scope too large, or dependencies incomplete.
+Ask for clarification when requirements are too vague or dependencies too incomplete to plan confidently; in unattended mode, proceed on explicitly stated assumptions instead.
 
 ### Step 2: Plan Approach
 
-Identify **durable architectural decisions** — data model, API contracts, and module boundaries that absorb change instead of exposing internals. Prefer interfaces that stay simpler than their implementations; avoid pass-through wrappers and shallow seams.
+Identify **durable architectural decisions** — data model, API contracts, and module boundaries that absorb change instead of exposing internals (see [deep-modules](../_shared/deep-modules.md)).
 
 **For complex work**, delegate codebase research to a sub-agent for unbiased answers:
 
@@ -39,7 +39,7 @@ Write 3–7 factual questions about existing systems, patterns, and integration
 **Inputs provided to sub-agent:** Role: [forge-scout](../_shared/roles/forge-scout.md), the research questions, codebase access.
 **Expected output:** One factual answer per question, with file paths and code references.
 
-If the runtime supports per-task model choice, prefer a **cheap fast model** for scout work — scouting is factual reconnaissance, not deep synthesis. Otherwise inherit the parent session model and keep the scout task narrow.
+Prefer a cheap fast model for scout work when the runtime supports per-task model choice.
 
 From the research, create a plan:
 - Durable decisions
@@ -65,27 +65,15 @@ When working from a plan file or free-text (no Issue number), use a descriptive
 
 Read AGENTS.md first. Follow project conventions strictly.
 
-Execute the work in vertical phases:
-- **Pre-flight before the first phase** — validate only the checks that matter for this change: codegen, config placement, required env vars, external dependencies, and existing code patterns.
-- **Per phase** — implement end to end across all needed layers, keep tests close to the behavior, and verify unfamiliar APIs before using them.
-- **Phase gate** — before moving on, run relevant tests/checks, confirm no new lint/type failures, and commit one logical change.
+Execute the work in vertical phases following [phase-execution](../_shared/phase-execution.md): pre-flight validation before the first phase, code and tests together within each phase, and a phase gate — tests pass, no new lint/type failures, one committed logical change — before the next.
 
 ### Step 5: Audit Pattern Consistency
 
-If you changed a pattern (error handling, component structure, API convention), grep for every other file using the old pattern and update them too:
-
-```bash
-grep -rn "<PATTERN>" <SEARCH_ROOT>/
-```
-
-Audit the **pattern shape**, not just a literal string. Choose the right search scope, re-grep after updating, and note any intentional exceptions in the PR.
+If you changed a pattern (error handling, component structure, API convention), grep for every other file using the old pattern and update them too — audit the pattern *shape*, not just a literal string. See [pattern-audit](../_shared/pattern-audit.md).
 
 ### Step 6: Update Documentation
 
-If behavior changed, update:
-- `docs/*.md` — architecture, API, development guides
-- `AGENTS.md` — if conventions or patterns changed
-- Code comments — only where logic isn't self-evident
+Update `docs/*.md` and `AGENTS.md` if behavior or conventions changed.
 
 ### Step 7: Run Final Quality Gate
 
@@ -105,9 +93,7 @@ Fix issues and commit fixes.
 git push -u origin <BRANCH_NAME>
 ```
 
-Create PR with conventional commit title format. Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: list of changes, test plan checklist, and quality checklist. Close the Issue when one exists.
-
-If the implementation requires manual deployment steps (env vars, infra changes, container/runtime config, migrations), add a prominent `> [!WARNING]` block at the top of the PR body.
+Create the PR with a conventional commit title. Lead the body with **why** (from the linked Issue's problem statement, or the commit history when none is linked), then the approach, changes list, test plan, and quality checklist; close the Issue when one exists. Add a `> [!WARNING]` block at the top for any manual deployment steps.
 
 ### Step 9: Summarize
 
diff --git a/skills/forge-reflect/SKILL.md b/skills/forge-reflect/SKILL.md
index 9478734..2371886 100644
--- a/skills/forge-reflect/SKILL.md
+++ b/skills/forge-reflect/SKILL.md
@@ -110,11 +110,7 @@ Aggregate findings from all review passes (Step 2), quality gate results (Step 3
 ## Guidelines
 
 - **Pattern consistency is the highest-value check**
-- **Tiny low-risk diffs stay inline** — avoid fresh-context overhead when the change is obviously small and this session didn't author it
-- **Keep review lean** — one reviewer by default, second only when risk justifies it
-- **Skip noise** — see [review rubric](../_shared/review-rubric.md)
 - **Bias toward fixing in the same PR** — only create Issues for confirmed deferrals that are truly larger or out of scope
-- **Aggregate and deduplicate** — merge overlapping findings, keep highest severity
 
 ## Related Skills
 
diff --git a/skills/forge-setup-project/SKILL.md b/skills/forge-setup-project/SKILL.md
index c131194..2d4b6ea 100644
--- a/skills/forge-setup-project/SKILL.md
+++ b/skills/forge-setup-project/SKILL.md
@@ -7,7 +7,7 @@ allowed-tools: Read, Edit, Write, Bash, Grep, Glob, AskUserQuestion
 
 # Set Up or Update Project Context Infrastructure
 
-Set up or update a project's context infrastructure for agentic engineering. Context is organized in three tiers:
+Context is organized in three tiers:
 
 | Tier | File(s) | Role |
 |------|---------|------|
@@ -25,27 +25,19 @@ Optional project root path (`$ARGUMENTS`; defaults to cwd). Optional: `-- <addit
 
 ## Process
 
-### Step 1: Determine Mode
+### Step 1: Assess What Exists
 
-Scan the project root for `AGENTS.md`, `CLAUDE.md`, `README.md`, and `docs/`.
-
-| Mode | Trigger | Behavior |
-|------|---------|----------|
-| **Setup** | Neither `AGENTS.md` nor `CLAUDE.md` exists | Generate tiered context from scratch |
-| **Audit & Update** | `AGENTS.md` exists | Score existing guidance, identify improvements, apply changes |
-| **Legacy Migration** | `CLAUDE.md` exists but `AGENTS.md` does not | Migrate `CLAUDE.md` to `AGENTS.md`, then update |
+Scan the project root for `AGENTS.md`, `CLAUDE.md`, `README.md`, and `docs/`. The file state determines the work: nothing exists → generate from scratch; legacy `CLAUDE.md` without `AGENTS.md` → migrate it to `AGENTS.md`, then update; `AGENTS.md` exists → audit and update.
 
 ### Step 2: Explore the Codebase
 
-Skip for greenfield projects (no code exists).
-
-Explore thoroughly: structure, language/runtime, scripts, CI/CD, lint/format/test config, docs. Classify each finding as **discoverable** (agents can find it) or **requires documentation** (decisions, conventions, failure modes). Only the second category belongs in context files.
+Explore structure, tooling, CI/CD, and docs (skip for greenfield projects). Classify each finding as **discoverable** (agents can find it themselves) or **requires documentation** (decisions, conventions, failure modes) — only the second category belongs in context files.
 
-Assess **agent readiness**: feedback loops (tests, linter, build cycle speed), module structure (entry points, boundaries), app legibility (bootable locally?), known risks.
+Assess **agent readiness**: feedback loops (tests, linter, build cycle speed), module structure, app legibility, known risks.
 
-### Step 3: Audit Existing Guidance (Audit & Legacy Migration modes only)
+### Step 3: Audit Existing Guidance
 
-Read all existing guidance files. Score each section:
+When guidance files already exist, score each section:
 
 | Criterion | Test |
 |-----------|------|
@@ -54,54 +46,19 @@ Read all existing guidance files. Score each section:
 | **Currency** | Does this match the current codebase? Verify commands, paths, patterns. |
 | **Signal density** | Ratio of actionable information to total words? |
 
-Present an audit report. Group recommendations into quick wins, high-value additions, and structural changes. Get user confirmation via AskUserQuestion before applying.
+Present an audit report grouped by impact and get user confirmation via AskUserQuestion before applying changes.
 
 ### Step 4: Gather Project Information
 
-Use AskUserQuestion to collect what cannot be determined from code.
-Incorporate any optional additional context when deciding what to ask, audit, or prioritize.
-
-**Always ask:**
-
-1. **Core principles** — "What 3-5 rules should always guide development?" Offer examples from what you observed.
-2. **Failure modes** — "What mistakes do agents or new developers repeat? What breaks?" Each entry must trace to an observed mistake.
-3. **Domain invariants** — "What rules must never be violated? What causes silent bugs?"
-
-**Ask only if ambiguous from code:**
-
-4. Conventions with enforcement mechanisms
-5. Confirm detected commands if multiple options exist
-6. How to handle existing meta files (if found without `AGENTS.md`)
-
-**Never ask** what's discoverable from code — language, framework, test runner, scripts, directory structure.
-
-For Audit/Migration modes, ask about gaps found in Step 3.
+Use AskUserQuestion for what code cannot reveal: core principles, repeated failure modes, and domain invariants — plus anything ambiguous from exploration and gaps surfaced by the Step 3 audit. Never ask what's discoverable from code. Incorporate any trailing context when deciding what to ask.
 
 ### Step 5: Generate or Update AGENTS.md
 
-Create or update `AGENTS.md`. Target **~150-200 lines**. Every line must pass the undiscoverability test.
-
-See [agents-md-template.md](references/agents-md-template.md) for the template structure.
-
-For **Legacy Migration**: migrate accepted content into `AGENTS.md`, fold duplicates, replace legacy file with symlink in Step 7.
+Create or update `AGENTS.md`. Target **~150-200 lines**; every line must pass the undiscoverability test. See [agents-md-template.md](references/agents-md-template.md) for the structure. When migrating, fold accepted legacy content in and replace the old file with a symlink in Step 7.
 
 ### Step 6: Generate or Update Tier 2 — docs/
 
-Only create docs with actual content. An empty doc wastes context.
-
-**Always created:**
-
-- `docs/architecture.md` — design decisions, data flow, module responsibilities. Not directory listings.
-- `docs/pr-workflow.md` — branch naming, PR checklist, review process. Reference AGENTS.md for commit format.
-
-**Created only when warranted** (offer via AskUserQuestion based on detection):
-
-- `docs/development.md` — when setup has gotchas or multi-step requirements
-- `docs/coding-guidelines.md` — when project has specific patterns worth codifying
-- `docs/testing.md` — when test patterns are non-obvious
-- Additional domain-specific docs as needed
-
-All Tier 2 docs must pass the undiscoverability test. Use tables for structured data. Include actual file paths.
+Create `docs/architecture.md` (design decisions, data flow, module responsibilities) and `docs/pr-workflow.md` (branch naming, PR checklist, review process); offer further docs (development, coding-guidelines, testing, domain-specific) via AskUserQuestion only when exploration surfaced content that warrants them. Every doc must pass the undiscoverability test — an empty doc wastes context.
 
 ### Step 7: Create Compatibility Symlink and Update .gitignore
 
@@ -111,27 +68,19 @@ rm -f CLAUDE.md
 ln -sf AGENTS.md CLAUDE.md
 ```
 
-If the platform doesn't support symlinks, stop and tell the user.
-
-Create or update `.gitignore` with entries matching the detected stack. Never overwrite an existing `.gitignore` — append only missing entries.
+If the platform doesn't support symlinks, stop and tell the user. Append missing stack-appropriate entries to `.gitignore` — never overwrite an existing one.
 
 ### Step 8: Create Human-Facing Files
 
-Create if it doesn't exist (this is for humans, not agent context):
-
-- **README.md** — project description, quick start, docs links. If one exists, ask via AskUserQuestion: replace, merge, or keep?
+Create `README.md` if it doesn't exist (project description, quick start, docs links — for humans, not agent context). If one exists, ask via AskUserQuestion: replace, merge, or keep?
 
 ### Step 9: Commit
 
-Stage and commit all new/modified files:
-- Setup mode: `docs: set up agentic context infrastructure`
-- Audit/Migration: `docs: update context infrastructure`
-
-Do not commit if: dry run requested, unrelated staged changes exist, or generated files have unresolved questions.
+Stage and commit the new/modified files: `docs: set up agentic context infrastructure` (or `docs: update context infrastructure` when updating). Skip the commit if unrelated staged changes exist or generated files have unresolved questions.
 
 ### Step 10: Summarize
 
-Report what was created/changed. See [output-format.md](references/output-format.md) for the structure. Include tier status with line counts, agent readiness assessment, and next steps.
+Report what was created/changed — see [output-format.md](references/output-format.md). Include tier status with line counts, agent readiness assessment, and next steps.
 
 ## Guidelines
 
diff --git a/skills/forge-setup-project/references/output-format.md b/skills/forge-setup-project/references/output-format.md
index b8c8fa1..d044218 100644
--- a/skills/forge-setup-project/references/output-format.md
+++ b/skills/forge-setup-project/references/output-format.md
@@ -1,8 +1,8 @@
 # Setup Summary Output Format
 
-Use the appropriate format based on mode.
+Use the format matching the work performed.
 
-## Setup Mode
+## Fresh Setup
 
 ```text
 ## Setup Complete
@@ -39,7 +39,7 @@ Use the appropriate format based on mode.
 4. Use /forge-create-issue to plan your first piece of work — or /forge-shape if the idea is still rough
 ```
 
-## Audit / Legacy Migration Mode
+## Audit / Update of Existing Guidance
 
 ```text
 ## Audit Complete
diff --git a/skills/forge-shape/SKILL.md b/skills/forge-shape/SKILL.md
index 6b042cb..2b57332 100644
--- a/skills/forge-shape/SKILL.md
+++ b/skills/forge-shape/SKILL.md
@@ -114,13 +114,8 @@ The summary is *evidence* of alignment, not the alignment itself. If the user re
 
 ## Guidelines
 
-- **One question at a time** — convergence comes from depth per answer, not breadth per prompt
-- **Always recommend an answer** — phrased as a recommendation, not a decision
-- **Challenge then converge** — push back on terminology conflicts, code contradictions, and vague boundaries before accepting an answer
-- **Use the project's language** — reference CONTEXT.md vocabulary; when new terms emerge, capture them immediately
 - **Problem over solution** — clarify what's wrong before proposing how to fix it
 - **Stay grounded** — reference specific code, files, and patterns, not abstractions
-- **Approach exploration is conditional** — skip Step 3 when shaping already surfaced the approach
 
 ## Related Skills
 
diff --git a/skills/forge-ship/SKILL.md b/skills/forge-ship/SKILL.md
index b789e04..201ee14 100644
--- a/skills/forge-ship/SKILL.md
+++ b/skills/forge-ship/SKILL.md
@@ -18,86 +18,22 @@ Same as `forge-implement` (`$ARGUMENTS`): Issue number/URL, plan file path, or f
 
 ### Step 1: Implement
 
-#### 1a. Understand
-
-Determine input type (Issue number/URL, plan file, or free-text). For Issues, fetch via the project's Issue tracker (see [issue-operations](../_shared/issue-operations.md)). Parse requirements and acceptance criteria. Flag if underspecified.
-
-#### 1b. Plan (delegate)
-
-For complex work, write 3–7 research questions and delegate to a sub-agent with the [forge-scout](../_shared/roles/forge-scout.md) role for unbiased codebase research. Prefer a cheap fast model for scout work. If the runtime does not support sub-agents, read the role file and answer the questions inline following its rules.
-
-**Inputs provided to sub-agent:** Role: [forge-scout](../_shared/roles/forge-scout.md), the research questions, codebase access.
-**Expected output:** One factual answer per question, with file paths and code references.
-
-From the research, create a plan: durable decisions, vertical phases (see [vertical-slicing](../_shared/vertical-slicing.md)), files to change, scope boundaries.
-
-Present the plan via AskUserQuestion. **In unattended mode:** skip approval and proceed.
-
-#### 1c. Branch
-
-```bash
-# Sync the default branch, then branch off it
-git fetch origin
-git checkout $(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
-git pull
-git checkout -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION>
-```
-
-When working from a plan file or free-text (no Issue number), use `<TYPE>/<BRIEF_DESCRIPTION>`.
-
-#### 1d. Execute
-
-Read AGENTS.md. Run pre-flight checks before the first phase (see [phase-execution](../_shared/phase-execution.md)). Implement in vertical phases — each phase spans all affected layers, includes tests, and ends with a commit. Run lint/types/tests at each phase gate.
-
-After changing a pattern, grep for the old pattern across the appropriate scope and update all instances (see [pattern-audit](../_shared/pattern-audit.md)).
-
-#### 1e. Update docs
-
-Update `docs/*.md` and `AGENTS.md` if behavior or conventions changed.
-
-#### 1f. Quality gate
-
-- [ ] Lint — no violations
-- [ ] Format — no violations
-- [ ] Type check — no errors
-- [ ] All tests pass
-- [ ] Test coverage ≥ 90% for new/modified code — if coverage tooling is not configured, flag this to the user and offer to set it up
-
-#### 1g. Push and create PR
-
-```bash
-git push -u origin <BRANCH_NAME>
-gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body "<PR_BODY>"
-```
-
-The PR title uses conventional commit format. Lead the summary with **why** the change was needed — pull the motivation from the linked Issue's problem statement; if no Issue is linked, derive it from the branch's commit history. Then briefly describe the approach taken. Include: changes list, test plan, quality checklist. Close the Issue when one exists. Add a `> [!WARNING]` block for manual deployment steps.
-
-Do not produce the implementation summary yet — the review will inform the final report.
+Execute the full [forge-implement](../forge-implement/SKILL.md) process with one modification: **do not produce implement's summary** — the review below informs the single final report.
 
 ### Step 2: Review (delegate)
 
-Follow the [review-delegation](../_shared/review-delegation.md) process: collect the diff from the implementation, use one fresh-context review pass by default (this session authored the diff, so the inline tiny-diff path never applies), add a second pass only when risk justifies it, and aggregate findings. Fresh context eliminates self-review bias when delegated review is used — reviewers have no memory of implementation decisions.
+Follow the [review-delegation](../_shared/review-delegation.md) process: collect the diff from the implementation, use one fresh-context review pass by default (this session authored the diff, so the inline tiny-diff path never applies), add a second pass only when risk justifies it, and aggregate findings.
 
 **Inputs provided to sub-agent:** the branch diff, changed file list, and project conventions per review-delegation.
 **Expected output:** Deduplicated findings grouped by file with severity tags (P0/P1/P2).
 
 ### Step 3: Triage Findings
 
-Use the aggregated findings from the review delegation.
-
-**In attended mode (default):** present each finding to the user with a recommendation.
-
-Bias hard toward **fix now**:
-- **Fix now** — default for in-scope findings and small-to-moderate changes that still fit this PR → apply fix, commit
-- **Defer** — only for larger changes that materially expand PR scope or are truly out of scope → create an Issue in the project's Issue tracker
-
-**In unattended mode:** auto-triage using severity plus scope from the [review rubric](../_shared/review-rubric.md):
+**In attended mode (default):** present each finding to the user with a recommendation, biased hard toward **fix now** — defer only changes that materially expand PR scope or are truly out of scope.
 
-- **P0–P2, if in scope and reasonably sized** → fix now, commit
-- **P1–P2, if truly out of scope or materially larger than the current PR** → defer, create an Issue in the project's Issue tracker
-- **P3** → ignore
+**In unattended mode:** auto-triage by severity plus scope from the [review rubric](../_shared/review-rubric.md): fix P0–P2 in-scope findings now; defer P1–P2 items that are truly out of scope or materially larger; ignore P3.
 
-For both modes, deferred items become Issues — see [issue-operations](../_shared/issue-operations.md) for provider-specific mechanics.
+Fixed findings are committed; deferred items become Issues — see [issue-operations](../_shared/issue-operations.md).
 
 ### Step 4: Summarize
 
@@ -131,16 +67,12 @@ Report implementation and review results together.
 ## Guidelines
 
 - **Even tiny diffs delegate here** — this session authored the changes, so inline review would be self-review
-- **Delegated review runs in fresh context** — reviewers have no implementation memory
-- **Keep review lean** — one reviewer by default, second only when risk justifies it
 - **Don't skip the review** — even if implementation felt clean
 - **Bias toward fixing in the same PR** — unless a finding is truly larger or out of scope
-- **Triage with the user** — unless `--unattended` (default to fixing in-scope findings)
-- **Graceful degradation** — works inline if no sub-agent support
 
 ## Related Skills
 
-**Components:** Composes `forge-implement` and `forge-reflect`.
+**Components:** Composes `forge-implement` and the fresh-context review flow shared with `forge-reflect` (`_shared/review-delegation.md`).
 **After peer review:** Use `forge-address-pr-feedback` to address reviewer comments.
 
 ## Example Usage

From 5f5caa520f91dba3997a57b5d409f01899bdb7e2 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Fri, 31 Jul 2026 08:09:30 +0200
Subject: [PATCH 08/10] =?UTF-8?q?fix:=20address=20PR=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20clarify=20skill-specific=20vs=20shared=20role=20fil?=
 =?UTF-8?q?e=20locations?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01Tr2WLSSA8A1x3ySScSzbkv
---
 docs/coding-guidelines.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/coding-guidelines.md b/docs/coding-guidelines.md
index 36cbaf9..df3cddc 100644
--- a/docs/coding-guidelines.md
+++ b/docs/coding-guidelines.md
@@ -51,7 +51,7 @@ Both can coexist in the same skill — `context: fork` handles Claude Code, `(de
 
 ### Using Roles in Delegate Steps
 
-When a delegation step benefits from a separated persona, extract it into a **role file** under the skill's `roles/` directory (see [Architecture — Skill & Role File Format](architecture.md#skill--role-file-format)). The skill then references the role and provides only task-specific instructions:
+When a delegation step benefits from a separated persona, extract it into a **role file** (see [Architecture — Skill & Role File Format](architecture.md#skill--role-file-format)). A role used by one skill lives in that skill's `roles/` directory; a role shared across skills lives in `skills/_shared/roles/`. The skill then references the role and provides only task-specific instructions:
 
 ```markdown
 #### Research (delegate)

From fd12a6c9d8fd273d25ad4f45f8de69f924df074c Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Fri, 31 Jul 2026 08:09:53 +0200
Subject: [PATCH 09/10] =?UTF-8?q?fix:=20address=20PR=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20raise=20gh=20label=20list=20page=20size=20for=20exh?=
 =?UTF-8?q?austive=20discovery?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01Tr2WLSSA8A1x3ySScSzbkv
---
 skills/_shared/issue-operations.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/_shared/issue-operations.md b/skills/_shared/issue-operations.md
index f82ccef..5ffb1a4 100644
--- a/skills/_shared/issue-operations.md
+++ b/skills/_shared/issue-operations.md
@@ -34,7 +34,7 @@ ISSUE_EOF
 **GitHub:** discover available labels before applying any, and add missing ones to an existing Issue:
 
 ```bash
-gh label list
+gh label list --limit 100   # defaults to 30 — raise it so discovery is exhaustive
 gh issue edit <ISSUE_NUMBER> --add-label "<LABEL>"
 ```
 

From e0a69f61a62091c6a365afcec3a8998b920ce7f0 Mon Sep 17 00:00:00 2001
From: Martin Gratzer <mgratzer@users.noreply.github.com>
Date: Fri, 31 Jul 2026 08:10:42 +0200
Subject: [PATCH 10/10] =?UTF-8?q?fix:=20address=20PR=20feedback=20?=
 =?UTF-8?q?=E2=80=94=20show=20quote-safe=20PR=20body=20invocation=20in=20i?=
 =?UTF-8?q?mplement=20step=208?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Claude-Session: https://claude.ai/code/session_01Tr2WLSSA8A1x3ySScSzbkv
---
 skills/forge-implement/SKILL.md | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/skills/forge-implement/SKILL.md b/skills/forge-implement/SKILL.md
index 567f315..611b573 100644
--- a/skills/forge-implement/SKILL.md
+++ b/skills/forge-implement/SKILL.md
@@ -95,6 +95,14 @@ git push -u origin <BRANCH_NAME>
 
 Create the PR with a conventional commit title. Lead the body with **why** (from the linked Issue's problem statement, or the commit history when none is linked), then the approach, changes list, test plan, and quality checklist; close the Issue when one exists. Add a `> [!WARNING]` block at the top for any manual deployment steps.
 
+Pass the body on stdin via a quoted heredoc — an inline `--body "..."` mangles multi-line text, backticks, and quotes:
+
+```bash
+gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body-file - <<'PR_EOF'
+<PR body>
+PR_EOF
+```
+
 ### Step 9: Summarize
 
 Report: branch name, PR link, commits made, files changed, tests added, docs updated, deferred items.