pi-dev-team 0.2.0

package/skills/human-oversight-protocol/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: human-oversight-protocol
+description: Approval gates, intervention commands, and transparency requirements. Use to classify any agent action as autonomous/notify/approve, respond to override/pause/stop commands, or structure a plan review before the implementation phase begins.
+role: orchestrator
+user-invocable: true
+---
+
+# Human Oversight Protocol
+
+## Constraints
+
+- Approval gates cannot be skipped; do not proceed past a gate without explicit human sign-off.
+- Ethical concerns are never auto-resolved; always escalate.
+- Intervention commands (`override`, `pause`, `stop`) take immediate effect with no debate.
+- Overrides accumulate; 3+ overrides on the same topic must trigger a config amend.
+
+## Plan Review as Primary Quality Gate
+
+The implementation plan is the primary review artifact, not the code. Traditional line-by-line code review is replaced by plan review for AI-generated work — 200 lines of plan is far more reviewable than 2,000 lines of generated code, and if the plan is correct and tests pass, the code is trustworthy.
+
+### Plan review checklist
+
+1. Does the research accurately describe how the system works? (File paths, data flows, dependencies)
+2. Does the plan address the right problem?
+3. Are the specified changes complete — no missing files or edge cases?
+4. Is the test strategy sufficient to verify correctness?
+5. Are there architectural concerns the plan missed?
+
+### When to still review code
+
+- Security-sensitive paths (authentication, authorization, crypto)
+- Performance-critical paths
+- When tests are insufficient to verify correctness
+- When the plan was ambiguous about implementation details
+
+## Approval Gates
+
+### Gate classification
+
+Every agent action falls into one of three categories:
+
+| Category | Description | Human involvement |
+|---|---|---|
+| **Autonomous** | Routine work within agent's defined scope | None — deliver output directly |
+| **Notify** | Significant but within scope; human should be aware | Deliver output + flag what was decided and why |
+| **Approve** | Outside routine scope or high-impact; human must sign off | Present proposal, wait for explicit approval |
+
+### Standard approval gates
+
+These actions always require human approval. Every gate below writes an
+`approval` entry to `.claude/metrics/config-changelog.jsonl` per the [Audit trail](#audit-trail)
+schema — `proposed`, `evidence_shown`, and `risks_surfaced` included.
+
+| Action | Rationale |
+|---|---|
+| Research findings (Phase 1 → 2) | Misunderstanding cascades into bad plans and bad code |
+| Implementation plan (Phase 2 → 3) | Plan correctness determines code correctness |
+| Production deployment | Irreversible, affects users |
+| Architecture change | High-impact, hard to reverse |
+| Database schema migration | Data integrity risk |
+| Security-sensitive code | Vulnerability risk |
+| Scope change | May affect timeline/budget |
+| Add a *new* external dependency (a package not already in the project) | Supply chain risk — a genuinely new package. A reversible minor/patch version **bump of an existing** dependency is **Medium** (decide-and-proceed), not this gate — see Escalation Paths. |
+| Delete files or data | Potentially irreversible |
+| Team structure change | Affects all agents |
+
+### Agent-specific gates
+
+Each agent defines additional gates in its `## Behavioral Guidelines > Decision Making` section. The Orchestrator consolidates these when coordinating multi-agent tasks.
+
+## Intervention Mechanisms
+
+### 1. Feedback (real-time correction)
+
+```
+amend: [modify existing behavior]
+learn: [teach something new]
+remember: [persist a preference]
+forget: [remove a preference]
+```
+
+- Does NOT stop the current task
+- Agent incorporates the feedback and continues
+- Full procedure: [Feedback & Learning](../feedback-learning/SKILL.md)
+
+### 2. Override (decision reversal)
+
+```
+override: [what was decided] → [what should be done instead]
+```
+
+- Stops the current approach; agent adopts the human's decision without debate
+- Logged as `override` in the [audit trail](#audit-trail) — `proposed` records the rejected proposal, `description` records the substituted decision, `evidence_shown`/`risks_surfaced` required
+- 3+ overrides on the same topic should trigger a config amend
+
+### 3. Pause (temporary halt)
+
+```
+pause
+```
+
+- Agent stops and presents current state
+- Human reviews and either resumes or redirects
+- No output is discarded
+
+### 4. Stop (emergency halt)
+
+```
+stop
+```
+
+- All agents halt immediately
+- Current output preserved but not delivered
+- Orchestrator presents a summary of what was in progress
+- Human decides: resume, redirect, or abandon
+
+## Transparency Requirements
+
+### Decision logging
+
+| Log entry | Where | When |
+|---|---|---|
+| Agent selected for task | Task metrics entry | At task start |
+| Routing rationale | Orchestrator metrics entry | At task start |
+| Approval gate triggered | Task metrics entry | When gate fires |
+| Human approval/rejection | Config changelog — [`proposed`/`evidence_shown`/`risks_surfaced` required](#audit-trail) | When human responds |
+| Override applied | Config changelog — [`proposed`/`evidence_shown`/`risks_surfaced` required](#audit-trail) | When override issued |
+
+### Decision visibility (Notify level)
+
+```
+Decision: [what was decided]
+Rationale: [why]
+Alternatives considered: [what else was evaluated]
+```
+
+### Audit trail
+
+**Canonical schema.** This section is the single canonical definition of the
+gate-decision audit entry — [Governance & Compliance](../governance-compliance/SKILL.md)
+and [Feedback & Learning](../feedback-learning/SKILL.md) reference it rather than
+restating the field definitions.
+
+All oversight events are appended to `.claude/metrics/config-changelog.jsonl` (one
+JSON object per line, append-only — existing entries are never modified, deleted,
+or migrated) with:
+
+| Field | Required for | Type | Rule |
+|---|---|---|---|
+| `type` | all | string | `approval` \| `override` \| `pause` \| `stop` |
+| `trigger` | all | string | `user` |
+| `description` | all | string | What happened and why. For `override`, this is the human's substituted decision (see below) |
+| `proposed` | `approval`, `override` — optional for `pause`/`stop` | string | One-line statement of what was put before the human — or, for `override`, what the agent had decided before the human reversed it |
+| `evidence_shown` | `approval`, `override` — optional for `pause`/`stop` | array of strings | **Artifact pointers only, never prose.** Each element is a repo-relative file path (e.g. `plans/<slug>.md`), `commit:<sha>`, `issue:#N` / `pr:#N`, or `.claude/metrics/<file>.jsonl@<line-or-timestamp>`. Every pointer must resolve to something that still exists after the session ends — never a chat transcript or ephemeral build/console output. If the evidence exists only as prose, write it to `.claude/memory/` first and point at that file. |
+| `risks_surfaced` | `approval`, `override` — optional for `pause`/`stop` | array of strings | Risks stated at the gate. `[]` is valid and explicit — it means "no risks were surfaced," distinguishing a reviewed-and-clear gate from a pre-change entry that omits the field entirely. |
+
+**Required for `approval` and `override`.** Optional for `pause`/`stop` — those
+record an interruption of state, not a decision over a proposal, so there is
+often nothing "proposed" or "shown" to record.
+
+**For `override` entries**: `proposed` records the rejected proposal — what the
+agent had decided; `description` records the human's substituted decision,
+matching the existing `override: [what was decided] → [what should be done
+instead]` grammar. Both fields must be reconstructable from the entry alone.
+
+**Non-interactive gates write identically.** When a gate auto-proceeds (`--yes`,
+`DEV_TEAM_AUTO_APPROVE=1`, or no TTY — see `/plan` and `/build`), the entry
+carries the same three fields; only `description`/`trigger` reflect the bypass
+(e.g. `"description": "Auto-approved (non-interactive) — no human gate"`).
+Unattended approvals are exactly where after-the-fact audit matters most.
+
+**Backward compatible, never migrated.** Entries written before this schema
+existed have no `proposed` / `evidence_shown` / `risks_surfaced` fields and
+remain valid — the changelog is append-only. Every consumer (feedback-learning's
+rollback lookup, governance-compliance's compliance queries and periodic
+checklist) must tolerate both shapes: an absent field means "written before
+this schema," not "malformed."
+
+**Example — phase-gate approval:**
+
+```json
+{
+  "timestamp": "2026-07-05T18:02:11Z",
+  "type": "approval",
+  "trigger": "user",
+  "description": "Plan approved for issue #867 (gate-decision audit fields)",
+  "proposed": "Implement the gate-decision schema extension per plans/issue-867-gate-decision-audit.md",
+  "evidence_shown": ["plans/issue-867-gate-decision-audit.md", "issue:#867"],
+  "risks_surfaced": []
+}
+```
+
+**Example — override:**
+
+```json
+{
+  "timestamp": "2026-07-05T18:10:44Z",
+  "type": "override",
+  "trigger": "user",
+  "description": "override: run the migration script → apply the schema change by hand-editing the two SKILL.md files",
+  "proposed": "Agent proposed running scripts/migrate_schema.py to apply the change",
+  "evidence_shown": [".claude/memory/build-issue-867.md"],
+  "risks_surfaced": ["Hand-editing risks missing a write site the script would have covered"]
+}
+```
+
+## Output
+
+Gate classification (autonomous / notify / approve) with rationale, or escalation summary with severity and recommended action. One decision per output; no restating of protocol rules.
+
+## Escalation Paths
+
+```
+Agent → Orchestrator → Human
+```
+
+1. Agent identifies the issue and flags it to the Orchestrator.
+2. **Absorb the uncertainty before escalating it.** Investigate within the codebase, run the relevant check, or dispatch the agent best placed to resolve it. Escalate only what investigation cannot settle — a raw unknown is not yet an escalation.
+3. Orchestrator classifies severity:
+   - **Low**: route to another agent with appropriate expertise; do not involve the human.
+   - **Medium** — reversible, low-blast-radius, and *not* one of the Standard approval gates above: **decide and proceed.** Commit to one path, state the rationale, act, and surface an explicit override — e.g. "Taking X because Y; reply `override` to change course." Do not hand the human a menu for a decision the agent can own and reverse. A **reversible minor/patch version bump of an existing dependency** (e.g. to pull a bug fix) is Medium: absorb the uncertainty first (read the changelog delta, run the suite against the bump), then **decide and proceed with an override affordance** — do not escalate it as a no-recommendation menu. It is distinct from *adding* a new package, which is the Standard gate below. (The Standard approval gates — *adding* a new external dependency, schema migration, scope change, deletes, etc. — are never downgraded to Medium; they remain Approve. A major-version bump, or one that pulls a genuinely new transitive package, leans Approve too.)
+   - **High** — irreversible or high-blast-radius: present to the human with full context, **no recommendation** (avoid anchoring), and wait. Reserved for genuinely human-only calls: the standard approval gates, ethical concerns, and anything hard to reverse.
+4. Human decides at the High tier (or when a committed Medium decision is overridden).
+5. The decision — or the committed Medium path plus any override — is logged and fed back to the requesting agent.

package/skills/issues-from-assessment/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: issues-from-assessment
+description: >-
+  Convert a `/cd-test-architecture` assessment into a parent + Phase-tagged
+  child issues on the tracker the operator points at (ADO, GitHub, GitLab,
+  Jira). Dispatches by parent URL host to the tracker's own CLI (`az boards`,
+  `gh`, `glab`, `acli`). When no parent URL is given, or when the required
+  CLI is not installed, falls back to local plan files under
+  `.claude/plans/<workflow>/` after informing the operator. Multi-workflow: called
+  by `/test-improve` (Phase 4), via its own
+  `--workflow` namespace so memory paths and tracker labels never collide.
+argument-hint: "<assessment-path> [--parent <issue-url>] [--repo-slug <slug>] [--workflow <name>] [--refactor-mode <no-refactor|refactor-allowed>] [--dry-run]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write
+---
+
+# Issues from Assessment
+
+<!-- pi-port-notes -->
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.
+<!-- pi-port-notes -->
+
+
+Role: worker. Converts the assessment produced by `/cd-test-architecture` into the tracker artifacts the calling test-improvement workflow expects (Feature/Epic + Phase-tagged Stories + Tasks with predecessor links), or — when no tracker CLI is available — into local plan files with the same structure. Lifts the preview-then-confirm + `gh issue create` patterns from `/issues-from-plan`.
+
+You have been invoked with the `/issues-from-assessment` command.
+
+## Parse Arguments
+
+Arguments: $ARGUMENTS
+
+- Positional: `<assessment-path>` — the file `/cd-test-architecture` wrote (`.dev-team-reports/cd-test-architecture-<app>.md`).
+- `--parent <issue-url>` — parent issue / Feature / Epic URL. Empty or omitted → local-files mode.
+- `--repo-slug <slug>` — slug used for the `.claude/memory/<workflow>/<slug>/` namespace. Defaults to the assessment file's `<app>` token.
+- `--workflow <name>` — the workflow namespace under `.claude/memory/` and `.claude/plans/`, and the leading tracker-label token. Defaults to `test-improve`. Callers pass their own namespace so parallel runs stay quarantined.
+- `--refactor-mode <no-refactor|refactor-allowed>` — optional; the caller's Phase-0 refactor choice. Defaults to `refactor-allowed` (unchanged behavior) when omitted. When `no-refactor`, the Phase-5 `[Refactor-for-testability]` work is emitted as **out-of-scope / skipped-in-no-refactor** plan entries — informational context only, **never actionable Stories** — so the written plan shows the coverage/behavior left on the table without offering refactor work this run will not do.
+- `--dry-run` — print the preview list and exit without creating anything.
+
+If `<assessment-path>` is absent or the file is missing, ask the operator to point at one.
+
+**Path + label templates.** Every filesystem path and every operator-visible tracker label in the Steps below carries `<workflow>` as a placeholder — the skill interpolates the resolved `--workflow` value at run time. No literal workflow name appears in a path or label string.
+
+## Steps
+
+### 1. Resolve sink (host-based dispatch + CLI probe)
+
+Parse the `--parent` URL host. Pick the CLI and probe it:
+
+| Host pattern | CLI | Probe |
+|---|---|---|
+| `dev.azure.com` | `az` (with `az boards` extension) | `command -v az >/dev/null 2>&1 && az extension show -n azure-devops >/dev/null 2>&1` |
+| `github.com` | `gh` | `command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1` |
+| `*.atlassian.net` | `acli` (Atlassian CLI) | `command -v acli >/dev/null 2>&1` — if missing, try REST with `$JIRA_TOKEN` |
+| `gitlab.com` / self-hosted GitLab | `glab` | `command -v glab >/dev/null 2>&1 && glab auth status >/dev/null 2>&1` |
+| *empty / omitted* | (none) | local-files mode |
+
+**If the probe fails**, tell the operator exactly what's missing and the canonical install / auth command, then fall back to local-files mode automatically. Example:
+
+```
+gh is not installed. Run `/project-init` to set up this repo's tooling, or install
+gh directly from https://cli.github.com/ and run `gh auth login`.
+Falling back to local-files mode — Stories will be written to .claude/plans/<workflow>/.
+```
+
+Record the resolved sink in `.claude/memory/<workflow>/<slug>/phase-1.md` so subsequent workers (`/coverage-baseline`, `/coverage-delta`, `/quality-targets-converge`) reuse the same dispatch decision.
+
+### 2. Read the assessment + derive children
+
+Parse the assessment file's sections per `/cd-test-architecture`'s contract:
+
+- **Components & patterns** → Feature description.
+- **Current-vs-correct test classification** → input to Phase-5 `[Re-scope]` Stories.
+- **Duplicate-coverage table** → Phase-5 `[De-duplicate]` Stories.
+- **CD-fitness gaps** → Phase-1 `[Gap]` Stories.
+- **Seam-reachability table per component** → Phase-4 `[Baseline]` Stories + Phase-5 `[Refactor-for-testability]` Stories. When `--refactor-mode no-refactor`, the `[Refactor-for-testability]` entries are emitted **out-of-scope (skipped-in-no-refactor)** — listed for visibility, not created as actionable Stories.
+- **Target architecture (per component)** → Phase-5 Stories per (component, layer) **EXCLUDING `[Component tests]`** — those Stories are created by `/gherkin-public` at the end of Phase 2, bound to the approved Gherkin scenarios.
+
+`[Component tests]` Stories are intentionally NOT created from the assessment. Creating them here would bind the test code to the *recommended* behavior in the assessment rather than the *approved* behavior in the Gherkin — and the Phase-2 human gate exists precisely to let the operator sharpen, add to, or correct the inferred behaviors before any test binds to them. `/gherkin-public --create-stories` produces them after the gate.
+
+For each derived child, build the title + body + phase-tag + predecessor list per the prompt's "ADO mapping" section in `reports/legacy-test-modernization-prompt.md`. The phase tags are `Phase-1` through `Phase-5`. Predecessor links follow the rules:
+
+- Every `[Baseline]` blocked by `[Audit]` (created in Phase 3, referenced by ID).
+- Every `[Refactor-for-testability]` blocked by the matching `[Baseline]`.
+- Every contract / integration / E2E / resilience Story blocked by the same component's `[Component tests]` (those IDs are filled in by `/gherkin-public` in Phase 2; this skill leaves a placeholder `Depends on: [Component tests] for <component> (created in Phase 2)` and the orchestrator backfills the link after Phase 2).
+- Every `[De-duplicate]` blocked by the Story that adds the kept-layer test.
+- Every `[Re-scope]` blocked by the Story that lands the test at the correct layer.
+
+### 3. Preview + confirm
+
+Print the full list (titles, types, predecessors, one-line acceptance summary) — grouped by phase. Ask:
+
+> Create these N issues against `<parent or local-files>`? (yes / no / dry-run output only)
+
+Do not call any tracker CLI or write any plan files until the operator answers `yes`. If `--dry-run` was given, print the list and exit zero.
+
+### 4. Create the parent (tracker mode only)
+
+If `--parent <url>` was provided, the parent already exists — capture its ID/number from the URL. Otherwise (local-files mode), create the parent **file**:
+
+```
+.claude/plans/<workflow>/FEATURE.md
+```
+
+Contents: the assessment summary (components table, target pre-merge gate, link to the MinimumCD component-test page), plus a placeholder block for running metric snapshots that `/coverage-baseline`, `/coverage-delta`, and `/quality-targets-converge` will append to.
+
+### 5. Create the children — partial-failure safe
+
+Two modes share the same control flow; only the create-call differs. Every tracker label carries `<workflow>` as its leading token so an operator scanning a mixed board can tell which workflow authored an issue.
+
+**Tracker mode.** For each child in dependency order, call the resolved CLI. Lift the GitHub pattern verbatim from `/issues-from-plan`, **including its Conventional Commit title rule** — GitHub is the only tracker here bound to `commitlint.config.js`/`issue-title-lint.yml`; ADO/GitLab/Jira titles keep the plain `[<phase-tag>] <component>` form from step 2 unchanged. For GitHub, prefix that same phase-tag title with a type — `test:` fits every phase here (audit/baseline/refactor-for-testability/de-duplicate/re-scope are all test-suite work): `test: [Baseline] <component>`. Verify with `printf '%s' "<title>" | npx commitlint --verbose` before creating.
+
+```bash
+# GitHub — github.com
+gh issue create --title "test: [<phase-tag>] <title>" --body "$(cat <<'EOF'
+## What to Build
+
+<one-paragraph behavior description>
+
+Part of #<parent>
+
+## Phase
+
+Phase-<n>
+
+## Depends On
+
+- #<predecessor>: <reason>   <!-- "none" if no predecessors -->
+
+## Acceptance Criteria
+
+- [ ] <gherkin scenario 1>
+- [ ] <gherkin scenario 2>
+
+## Architectural Context
+
+<assessment excerpt for this row>
+
+## Testing Approach
+
+<which test layer, which doubles, which pipeline stage>
+EOF
+)" --label "<workflow>,phase-<n>,<minimumcd-type>"
+```
+
+For the other trackers:
+
+```bash
+# Azure DevOps — dev.azure.com
+az boards work-item create \
+  --org "https://dev.azure.com/<org>" --project "<project>" \
+  --type "User Story" --title "<title>" \
+  --description "<body>" \
+  --fields "Microsoft.VSTS.Common.AcceptanceCriteria=<gherkin>" \
+           "System.Tags=<workflow>; phase-<n>; <minimumcd-type>"
+# Then `az boards work-item relation add` for parent + predecessor links.
+
+# GitLab — gitlab.com / self-hosted
+glab issue create --title "<title>" --description "<body>" \
+  --label "<workflow>,phase-<n>,<minimumcd-type>" \
+  --linked-mr none
+# Predecessor links via `glab issue note add` referencing #<id>.
+
+# Jira — *.atlassian.net
+acli jira workitem create --type Story --summary "<title>" \
+  --description "<body>" \
+  --label "<workflow>" --label "phase-<n>" --label "<minimumcd-type>"
+# Parent + `is blocked by` links via `acli jira workitem link`.
+```
+
+Record the **child-slug → tracker-id** map as you go (in `.claude/memory/<workflow>/<slug>/issue-map.json`).
+
+**Local-files mode.** Write one `.claude/plans/<workflow>/phase-<n>/<child-slug>.md` per child. The file's body holds the same fields the tracker would (Phase, Depends On, Acceptance Criteria, Architectural Context, Testing Approach). Cross-Story predecessor links use **relative paths** (e.g. `Blocked by: ../phase-4/baseline-orders-api.md`). A `Status:` line at the top defaults to `Open` and gets flipped to `Done: <date>` by `/coverage-delta` and `/quality-targets-converge` when the matching gate passes.
+
+**Partial-failure safety.** If any CLI call (or file write) fails partway, do **not** abort silently. Report:
+
+- Which children were created (with IDs / paths).
+- Which were not.
+- The first failure's stderr.
+
+Leave the partial state on disk and let the operator decide whether to resume.
+
+### 6. Backfill predecessor links
+
+For tracker mode, after every child exists, walk the child-slug → tracker-id map and add the predecessor links:
+
+- GitHub: append `Depends on #<n>` lines to the body, or use `gh issue edit` to update the issue.
+- ADO: `az boards work-item relation add --relation-type "System.LinkTypes.Dependency-Reverse" --id <child> --target-id <predecessor>`.
+- GitLab: `glab issue note add <child-iid> --message "Depends on #<predecessor>"`.
+- Jira: `acli jira workitem link --inward "is blocked by" --from <child> --to <predecessor>`.
+
+For local-files mode, the `Blocked by:` lines were written in Step 5 — no backfill needed.
+
+### 7. Persist phase-1 progress
+
+Write `.claude/memory/<workflow>/<slug>/phase-1.md` with:
+
+- Resolved sink (CLI + parent URL or `local-files`).
+- Phase counts per phase tag.
+- The child-slug → tracker-id (or relative path) map.
+- The assessment file path.
+- Quality targets in force.
+
+### 8. Report
+
+Print:
+
+- Parent: `<URL>` or `.claude/plans/<workflow>/FEATURE.md`.
+- N children created across Phases 1, 2, 4, 5 (Phase-3 Stories are created by `/test-audit-disable` + `/coverage-baseline` later).
+- Any partial-failure messages from Step 5.
+- The path to `.claude/memory/<workflow>/<slug>/phase-1.md` for `/continue`.
+
+## Examples / Integration
+
+- `/test-improve` invokes this worker with `--workflow test-improve` from its Phase 4; paths resolve under `.claude/memory/test-improve/<slug>/` and labels lead with `test-improve`.
+- `/test-improve` invokes this worker with `--workflow test-improve`; paths resolve under `.claude/memory/test-improve/<slug>/` and labels lead with `test-improve`, keeping a mixed board unambiguous when both workflows are active.
+
+## Notes
+
+- This worker is the only place tracker-CLI knowledge sits. Adding a new tracker means one new branch in Steps 1 + 5; no other skill changes.
+- `/issues-from-plan` (the existing GitHub-only issue creator) handles a *plan*; this worker handles a *test-architecture assessment*. The two are intentionally separate — overlap is only the `gh issue create` snippet.
+- Adding a new workflow caller means passing a new `--workflow <name>` value; no path or label edits inside this skill are required because both are templated.

package/skills/issues-from-plan/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: issues-from-plan
+description: >-
+  Break a plan into independently-grabbable GitHub issues. Use when the user
+  says "create issues from this plan", "break this into tickets", "file issues",
+  or wants to distribute plan steps across a team.
+argument-hint: "[plan file path]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write
+---
+
+# Issues from Plan
+
+<!-- pi-port-notes -->
+## pi port notes (read first)
+
+- Issue and comment text follows the "GitHub text style" from the system prompt. Keep every heading, section and marker that this skill's template requires, because later steps read them. Write the prose inside them plainly and briefly. If the template itself breaks a rule (for example a required list that is longer than the limit), send the same `gh` command again unchanged: the extension blocks it only once.
+<!-- pi-port-notes -->
+
+
+Role: orchestrator.
+
+Break an implementation plan into GitHub issues that can be worked independently.
+
+## Orchestrator constraints
+
+1. Decompose the plan into issues; do not implement.
+2. Preserve plan ordering and dependencies as issue links.
+3. **Be concise.** Report created issue numbers, no narration.
+
+## Process
+
+### 1. Find the Plan
+
+If a path is provided in arguments, read that file. Otherwise, look for the most recent plan in:
+
+- Active plan in conversation context
+- `.claude/memory/` directory (phase progress files)
+- `plans/` directory
+
+Arguments: $ARGUMENTS
+
+If no plan is found, ask the user to point you to one.
+
+### 2. Analyze the Plan
+
+Read the plan and identify each **slice** (`### Slice <id>:`), its acceptance criteria, and the shared architectural decisions. Derive the dependency links from the **DAG, not file order** — do not hand-infer them:
+
+```bash
+python3 "${CLAUDE_PLUGIN_ROOT}/scripts/issue_deps.py" <plan-file>
+```
+
+This returns `{ "<slice>": ["<dep slice>", ...] }` — each slice's direct predecessors. A slice listed earlier in the file carries **no** dependency on a later one unless the DAG says so.
+
+Then locate the plan's **spec** (the linked spec artifact or `docs/specs/<...>.md`); it becomes the **parent** issue. **If the plan has no associated spec, report that and create no parent issue** (and no children) — stop here.
+
+### 3. Draft Issues
+
+For each unit of work, draft an issue with:
+
+- **Title**: a Conventional Commit — `<type>: <short, action-oriented summary>`
+  (e.g., `feat: add user authentication endpoint`), matching
+  `commitlint.config.js`'s ruleset. These titles seed branch names, PR
+  titles, and release versions once the sub-issue's PR merges, and
+  `.github/workflows/issue-title-lint.yml` labels
+  `needs-conventional-title` on anything that doesn't conform — check
+  proactively instead of relying on that backstop:
+  `printf '%s' "<title>" | npx commitlint --verbose`. If it exits non-zero,
+  fix the title before creating the issue.
+- **Body**:
+  - What to build (behavior description, not implementation details)
+  - Acceptance criteria as checkboxes
+  - Dependencies on other issues (by title reference)
+  - Relevant architectural decisions from the plan
+  - Testing approach
+- **Labels**: suggest appropriate labels if the repo uses them
+
+### 4. Review with User
+
+Present the issue list as a numbered summary:
+
+```
+1. [Title] — [one-line description] (depends on: none)
+2. [Title] — [one-line description] (depends on: #1)
+3. [Title] — [one-line description] (depends on: #1)
+...
+```
+
+Ask: "Does this breakdown look right? Should any issues be merged or split?"
+
+Wait for approval before creating.
+
+### 5. Create Issues (parent spec, then slice children)
+
+Create the **parent** issue from the spec first, then one **child** issue per slice linked to it, then backfill the sibling `depends on #N` links from the `scripts/issue_deps.py` map:
+
+1. **Parent (spec):** `gh issue create` from the spec (intent + acceptance summary); capture its number as `$PARENT`. If step 2 found no spec, skip everything — no parent, no children.
+2. **Children (slices):** for each slice, `gh issue create` with `Part of #$PARENT` in the body. Record the **slice-id → issue-number** mapping as you go.
+3. **DAG links:** for each slice, look up its predecessors from the `scripts/issue_deps.py` map, translate them to the child issue numbers, and set the child's `## Depends On` to `depends on #N` for each (a slice with no predecessors says "none"). Links come from the DAG map, never from file order.
+4. **Partial-failure safety:** if any `gh` call fails partway, do **not** abort silently — report which issues were created (with numbers) and which were not, then let the plan flow continue. Never leave a half-created state unreported.
+
+```bash
+gh issue create --title "Issue title" --body "$(cat <<'EOF'
+## What to Build
+
+[Behavior description — what this slice delivers end-to-end]
+
+Part of #<parent>
+
+## Depends On
+
+- #<number>: [brief reason]   <!-- from scripts/issue_deps.py; "none" if no predecessors -->
+
+## Acceptance Criteria
+
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] All tests pass
+
+## Architectural Context
+
+[Relevant decisions from the plan that apply to this issue]
+
+## Testing Approach
+
+[What to test and how — behavior-level, not implementation-level]
+EOF
+)"
+```
+
+### 6. Present Results
+
+List all created issue URLs with their titles. Note the dependency graph.