diff --git a/AGENTS.md b/AGENTS.md index f17cb09..68a37cb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,8 +35,8 @@ gh pr list # list open pull requests 3. **Never invent content** — use `` 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 `-- ` 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 +6. **One invocation convention** — every skill supports optional trailing execution context via `-- ` 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 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 bf0d595..fe25214 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 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. 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). -**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 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. -**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** — orchestrates other skills (currently only `forge-ship`). +**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. -**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. +**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. -**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/_shared/pattern-audit.md). -**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). - -**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** — `-- ` 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. diff --git a/README.md b/README.md index 3fdc8b5..c4b6acf 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@

Agent skills for structured development with pluggable issue tracking.
- One workflow. Six skills. From idea to review-ready code. + One workflow. Seven skills. From idea to review-ready code.

@@ -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 `** | **Implement + review in one invocation** | -Skills with structured primary input also accept optional trailing execution guidance using `-- `. +All skills accept optional trailing execution guidance using `-- `. ## Workflow @@ -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; 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 c805493..abdd541 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 @@ -49,21 +49,21 @@ 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 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-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-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 stays inline for tiny low-risk diffs and otherwise uses one fresh-context reviewer by default, 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 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 `-- ` 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 `-- ` as the final segment. ## Operating Constraints @@ -74,15 +74,15 @@ 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 (~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 | -| Skill composition | Composite skills reference other skills by path | Keeps orchestrators lean; avoids duplicating step-level instructions across skills | +| 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 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: `/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..df3cddc 100644 --- a/docs/coding-guidelines.md +++ b/docs/coding-guidelines.md @@ -19,9 +19,10 @@ 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. +- `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 @@ -50,17 +51,17 @@ 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** (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) -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. @@ -103,27 +104,27 @@ Conventions shared across skills. When modifying any, update every skill that re | Convention | Format | Referenced In | |------------|--------|---------------| -| Conventional commits | `(): ` — 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 | `(): ` — 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 — 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 `-- ` 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 — 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 `-- ` as the final invocation segment | 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 | -| 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 | +| 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 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 | | 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 | +| 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 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 | @@ -135,7 +136,8 @@ 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. +- **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/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\|-- " \ - skills/forge-setup-project \ - skills/forge-shape \ - skills/forge-implement \ - skills/forge-reflect \ - skills/forge-address-pr-feedback + grep -r "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..29f6aba 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -49,19 +49,14 @@ 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\|-- " \ - 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\|-- " 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/_shared/issue-operations.md b/skills/_shared/issue-operations.md index 0bf13a4..5ffb1a4 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 --limit 100 # defaults to 30 — raise it so discovery is exhaustive +gh issue edit --add-label "