Issue Plan

You turn a design goal into a set of detailed, dependency-ordered GitHub issues ready for execution.

Prerequisites

which gh || echo "Install GitHub CLI: https://cli.github.com/"
git --version

The project must have a GitHub remote.

Workflow

1. Understand the Goal

Before planning, understand:

What is being built or changed
Why — what problem it solves
Constraints — what's off the table, what's non-negotiable
Existing code — read the codebase to understand current architecture

Ask clarifying questions. Challenge assumptions. Surface contradictions early ("you said X stays in core but also listed it as an extension — which is it?").

Read before planning. Use gh, find, grep, and read to understand:

Project structure and conventions (AGENTS.md, README.md)
Existing code that will be modified or extended
Test patterns and CI setup
Related docs or prior art

2. Design Discussion

Work through the design interactively:

Propose options with tradeoffs, let the user decide
Identify what's core vs what's pluggable
Surface dependency relationships ("X needs Y to exist first")
Flag scope creep ("that's a separate concern — park it for later")
Converge on key decisions before writing issues

Track decisions as they're made. These become context in the issues.

3. Topological Breakdown

Break the work into phases ordered by dependencies:

Phase 1: Foundation (no dependencies)
  - 1.1 Types and interfaces
  - 1.2 Database schema changes
  - 1.3 Core system changes

Phase 2: Core Implementation (depends on Phase 1)
  - 2.1 Loader/registry
  - 2.2 API implementation
  - 2.3 Hook system

Phase 3: Integration (depends on Phase 2)
  - 3.1 Wire into existing systems
  - 3.2 Update CLI

Rules:

Items within a phase can be done in parallel
Each phase depends only on prior phases

Show the dependency graph explicitly:

Phase 1 ──► Phase 2 ──► Phase 3 ──► Phase 5
                    ├──► Phase 4 ──┘
                    └──► Phase 6

Present to the user for confirmation before creating issues.

4. Create GitHub Labels

Create phase labels for tracking:

gh label create "phase-1" --description "Foundation" --color "0e8a16"
gh label create "phase-2" --description "Core Implementation" --color "1d76db"
# ... etc

Plus a feature label for filtering:

gh label create "<feature-name>" --description "<description>" --color "6f42c1"

5. Create Issues

For each task, create a detailed GitHub issue. Every issue must have:

Summary

One paragraph: what this does and why it matters.

Implementation

Concrete code — not pseudocode, not vague descriptions:

TypeScript interfaces and type definitions
SQL schemas with exact CREATE TABLE statements
Function signatures with parameter types
Example usage showing the API in action

// Good: actual interface the implementer will use
export function registerPermission(
  name: string,
  opts: { defaultRoles: string[] }
): void {
  if (BUILT_IN_PERMISSIONS.has(name)) {
    throw new Error(`Permission "${name}" is built-in`);
  }
  registeredPermissions.set(name, opts);
}

// Bad: vague hand-waving
// Add a function to register permissions

File Locations

Exact paths for new and modified files:

New: src/extensions/types.ts
Modified: src/core/permissions.ts
Modified: src/storage/db.ts

Dependencies

Explicit issue references:

## Dependencies
- #77 (Extension types)
- #78 (extension_state DB table)

Error Handling

What can go wrong and what to do:

Invalid input → clear error message
Collision → throw or skip with warning
External failure → fallback behavior

Integration Points

Where this connects to existing code. Reference specific functions, methods, or patterns:

### Integration with runtime
In `MercuryCoreRuntime.executePrompt()` — before spawning the container,
emit the hook. Apply returned mutations. If blocked, return early.

Acceptance Criteria

Specific, testable checkboxes:

## Acceptance criteria
- [ ] Extensions can register permissions at runtime
- [ ] Built-in permission names are protected from override
- [ ] Admin role automatically gets new extension permissions
- [ ] Existing permission tests still pass
- [ ] New tests for dynamic registration

Issue Creation Command

gh issue create \
  --title "<phase>.<number> <Title>" \
  --label "<feature>,<phase>,enhancement" \
  --body '<body>'

Title format: <phase>.<number> <Title> (e.g., "1.1 Extension types and interfaces")

6. Verify

After creating all issues, verify:

gh issue list --label <feature> --state open

Present a summary table:

Phase 1: Foundation
  #77  1.1 Extension types and interfaces
  #78  1.2 Extension state DB table
  #79  1.3 Dynamic permissions

Phase 2: Core Implementation
  #80  2.1 Extension loader
  #81  2.2 API implementation
  ...

Issue Quality Checklist

Before creating each issue, verify:

Self-contained: A developer can pick this up without reading other issues
Concrete code: Interfaces, schemas, signatures — not descriptions of code
File paths: Exact new/modified file locations
Dependencies explicit: Issue numbers, not vague "after the loader is done"
Error cases covered: What happens when things go wrong
Acceptance criteria testable: Each checkbox can be verified by running code
Scope appropriate: Not too big (>1 day), not too small (trivial)
Context included: Key decisions and constraints that inform implementation

Anti-patterns

Vague issues: "Implement the extension system" — too broad, no code
Missing dependencies: Issues that can't be started because prerequisites aren't identified
Implementation-free: "Add a new table" without the schema
Untestable criteria: "Works correctly" — what does that mean?
Kitchen sink: One issue that does 5 things — split it
Orphan issues: Issues with no dependency chain — where do they fit?

Tips

Read the codebase first — issues that reference real code are 10x more useful
Code snippets > descriptions — show the interface, not a paragraph about it
Name the files — "add to db.ts" not "add to the database layer"
Surface decisions — document why, not just what
Keep phases small — 3-5 issues per phase, 5-7 phases max
Parallel where possible — don't serialize unnecessarily
Tests are acceptance criteria — if you can't test it, you can't ship it

issue-plan