app-issue-breakdown

name	app-issue-breakdown
description	Convert app plans, design docs, product briefs, or launch checklists into implementation-ready GitHub issues. Use when Codex needs to create coding issues, human setup issues, labels, milestones, dependencies, acceptance criteria, test notes, env var placeholder tasks, parallel workstreams, or copy-ready issue bodies for building a scoped app.

App Issue Breakdown

Goal

Turn a product/design plan into small, parallelizable issues that coding agents and humans can work on at the same time. Each issue should have a clear outcome, dependencies, acceptance criteria, test notes, and enough implementation context to start without rereading the whole plan.

Core Principle

Human setup tasks are parallel work, not blockers to avoid planning. If a human can go create an API key, verify a domain, approve copy, collect assets, configure DNS, or create a Firebase/Stripe/Resend resource while coding continues, create a separate human-task issue for it and make code issues consume documented placeholders.

For environment variables:

• Coding issues should maintain a canonical env inventory.
• If .env.example does not exist, create or request an issue to create it.
• .env.example should include every expected key with an empty value or obvious placeholder.
• Human issues should tell the user exactly which key to populate, for example MY_API_KEY=.
• Code should read env vars by canonical names and fail clearly in development when required values are missing.

Workflow

1. Read the plan. Identify product surface, architecture, services, integrations, legal/content work, tests, deployment, and launch tasks.

2. Classify workstreams. Use references/workstreams.md to group tasks into coding, human setup, content/design, QA, and launch/ops.

3. Build the dependency graph. Human setup tasks should run in parallel when possible. Code tasks may depend on env variable names and mocks/stubs before real values exist. Only mark tasks as blocked when the actual value/resource is required for verification or production launch.

4. Define canonical env keys. Read references/env-placeholders.md. Produce or update the env inventory before integration issues depend on secrets.

5. Create issues. Read references/issue-format.md. Use consistent titles, labels, dependencies, acceptance criteria, and tests.

6. Use GitHub tools when available. If a GitHub tool is available and repo context is clear, create issues. Otherwise output copy-ready issue bodies. Do not invent issue links.

7. Preserve scope. Keep issues implementable in one focused pass. Split vague or broad issues. Do not bury human setup inside coding tasks.

Labels

Use these labels when available:

• planning
• frontend
• backend
• firebase
• stripe
• resend
• analytics
• seo
• legal
• testing
• ci
• docs
• human-task
• content
• design
• blocked

Issue Ordering

Prefer this order:

1. Foundation and docs.
2. Env inventory and placeholders.
3. Human setup tasks that can run immediately.
4. App shell and core architecture.
5. Integration stubs and local/test-mode paths.
6. Feature implementation.
7. Integration verification using real credentials.
8. Testing.
9. Deploy/launch.

Outputs

Always produce:

• Milestone or issue grouping strategy.
• Dependency notes.
• Canonical env key inventory.
• Coding issues.
• Human setup issues designed for parallel execution.
• QA/testing issues.
• Launch/ops issues.

For each human task, include:

• Exact account/resource to create.
• Exact env key or repo secret to set.
• Where to set it.
• How a coder can proceed before it is done.
• How to verify completion.