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