michaelliv 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