Task Prd Creator

Task & PRD Creator

Write a clear, actionable PRD or task. Output depends on where the user tracks work.

Contract

Inputs:

• Feature, bug, enhancement, or planning request
• Destination preference: GitHub issue, local PRD/task file, or both
• Optional parent issue, labels, assignee, and priority

Outputs:

• Draft PRD or task body
• Destination-specific create command or file path
• Created issue/file URL or path after approval

Creates/Modifies:

• Local .agents/memory/<kebab-name>.md PRD files only after draft approval
• GitHub issues/sub-issues only after draft approval

External Side Effects:

• Reads GitHub issue state
• May create GitHub issues, sub-issues, or issue branches

Confirmation Required:

• Always show the draft before creating files or GitHub issues
• Ask before linking sub-issues or creating issue branches

Delegates To:

• spec-first when implementation constraints are still unclear
• tdd when the work should be executed test-first
• gh-fix-ci for CI failures after implementation
• roadmap-analyzer for roadmap-level planning
• cto-advisor for technical strategy and architecture tradeoffs

Step 1: Detect workflow preference

Check in order:

1. User explicitly says "GitHub issue", "local file", or both 2. Check if gh auth status succeeds and a GitHub remote exists → GitHub available 3. If ambiguous, ask: "GitHub issue, local PRD file in .agents/memory/, or both?"

Step 2: Understand the request

Ask only what's missing — don't interrogate if context is clear:

• What problem does this solve?
• Who's affected? (user-facing, internal, infra)
• Any hard constraints or dependencies?
• Is this part of a larger epic? (→ sub-issue)
• Priority: critical / high / medium / low

Step 3: Research before writing

• Read relevant architecture docs if available (.agents/memory/ — look for architecture, summary, or context files)
• Search codebase for related patterns
• Check for existing issues on same topic: gh issue list --search "[keyword]"

Step 4: Write the PRD

See references/full-guide.md for the full PRD structure.

A good PRD has:

• Problem — why this exists, what breaks without it
• Goal — one sentence, measurable outcome
• Scope — what's in, what's explicitly out
• Acceptance criteria — EARS (WHEN/WHILE/WHERE/IF … THE SYSTEM SHALL …), testable, not vague
• Technical notes — approach, risks, dependencies

Keep it tight. No filler. Acceptance criteria must be EARS-shaped and checkable by a human.

Agent-ready issue rules

When the output is an issue for an autonomous or AFK agent, write it as an agent brief, not a stream-of-consciousness plan:

• Describe behavior and contracts, not file-by-file instructions.
• Avoid line numbers and brittle file paths unless the path is itself the contract.
• Include current behavior, desired behavior, acceptance criteria, and out of scope.
• Name public interfaces, CLI commands, API shapes, config keys, or data contracts when known.
• Keep implementation notes as constraints, not a script the agent must follow.

Vertical-slice breakdown

When breaking an epic, PRD, or plan into issues:

• Prefer thin vertical slices that produce a verifiable outcome.
• Mark each issue as AFK when an agent can complete it without more human input.
• Mark each issue as HITL when it needs a human decision, design review, credential, or product judgment.
• Publish blockers before blocked issues so dependencies can reference real issue IDs.
• Keep each sub-issue small enough for one focused PR.

Step 5: Output to correct destination

GitHub (primary if available)

New issue:

gh issue create \
  --title "[type]: clear title" \
  --body "$(cat <<'BODY'
[PRD content here]
BODY
)" \
  --label "type:feature" \
  --assignee "@me"

Sub-issue (linked to parent):

# Create sub-issue
gh issue create --title "..." --body "..." 

# Link as sub-issue to parent #N
gh issue develop N --checkout  # only if needed
# Use: gh api repos/{owner}/{repo}/issues/{parent}/sub_issues --method POST -f sub_issue_id={child_id}

Draft PR from issue:

gh issue develop [issue-number] --branch "feature/[name]"

Local files (optional, or when no GitHub)

• PRD: .agents/memory/[kebab-name].md

See references/full-guide.md for local file templates.

Step 6: Get approval before creating

Show the draft PRD. Wait for "looks good" or edits. Then create.

Rules

• disable-model-invocation: true → only runs when user explicitly invokes
• Never create files or GitHub issues without user seeing the draft first
• Sub-issues should be small enough to ship in one PR
• If requirements are unclear, write the problem statement first — not the solution
• If rejecting an enhancement as out of scope, record durable reasoning in .out-of-scope/<concept>.md when the repo uses local out-of-scope memory.

Related

• spec-first — spec-driven development before writing code
• tdd — red-green-refactor execution for tasks with clear behavior
• gh-fix-ci — fix CI on existing PRs
• roadmap-analyzer — broader roadmap planning
• cto-advisor — technical strategy and architecture tradeoffs

Task & PRD Creator — Full Guide

Workflow detection

---

PRD structure

Every PRD — whether GitHub issue body or local file — uses this structure. Skip sections that don't apply. Never leave placeholder text in.

## Problem

[What breaks, what's missing, why this matters. 2-4 sentences max.]

## Goal

[One sentence. Measurable. "Users can X without Y friction."]

## Scope

**In:**
- [specific thing 1]
- [specific thing 2]

**Out:**
- [explicitly excluded thing — prevents scope creep]

## Acceptance criteria

- [ ] WHEN [trigger] THE SYSTEM SHALL [observable response].
- [ ] WHILE [state] THE SYSTEM SHALL [response].
- [ ] IF [edge or failure condition] THEN THE SYSTEM SHALL [handled response].

## Technical notes

**Approach:** [Pattern to follow, key architectural decision]
**Risks:** [What could go wrong, unknowns]
**Dependencies:** [Other issues, external services, env vars needed]
**Files likely affected:** [rough list if known]

## Links

- Parent issue: #N (if sub-issue)
- Related: #N, #N
- Design: [Figma/Linear link if any]

---

Agent brief structure

Use this when the issue is intended for an autonomous agent to implement. The brief is the durable contract; prior comments and PRDs are supporting context.

## Agent Brief

**Type:** bug | enhancement | refactor | chore
**Mode:** AFK | HITL
**Priority:** critical | high | medium | low

## Current behavior

[What happens now. For bugs, name the broken user or caller behavior.]

## Desired behavior

[What should be true after this issue is complete. Include edge cases.]

## Key contracts

- `[public interface, endpoint, CLI command, config key, or data shape]`:
  [what must be preserved or changed]

## Acceptance criteria

- [ ] WHEN [trigger] THE SYSTEM SHALL [observable response].
- [ ] IF [edge condition] THEN THE SYSTEM SHALL [handled response].

## Verification

- [ ] [Exact command, manual check, or browser flow]

## Out of scope

- [Thing that should not be changed]
- [Adjacent feature that belongs in a separate issue]

Write from behavior to implementation. Do not include line numbers. Avoid file paths unless the task is explicitly about a file path, generated artifact, or configuration location.

---

Vertical-slice issue breakdown

Break large work into independently grabbable slices:

## Slice

**Mode:** AFK | HITL
**Blocked by:** None | #123
**User stories covered:** [short list]

## What to build

[One narrow end-to-end behavior, not a layer-by-layer task list.]

## Acceptance criteria

- [ ] WHEN [trigger] THE SYSTEM SHALL [demoable, mechanically verifiable result].

## Verification

- [ ] [Narrow command or review step]

Use AFK for issues an agent can complete from the written context. Use HITL for issues that require product judgment, design approval, credentials, manual access, legal/compliance review, or a human-only decision.

Prefer many thin issues over a few thick ones, but do not split so far that a completed issue has no user, caller, or maintainer-visible result.

---

Out-of-scope memory

When an enhancement is rejected as wontfix, preserve the decision if future requests are likely:

# [Concept Name]

## Decision

This project does not support [concept].

## Why this is out of scope

[Durable reasoning: project scope, technical constraint, strategy, or product
positioning. Avoid temporary reasons like "not this sprint".]

## Prior requests

- #123 - [short title]

Create one .out-of-scope/<concept>.md file per concept, not per issue. When a new issue matches an existing rejected concept, surface the prior decision and ask whether it still stands before closing or reopening the idea.

---

Issue types and titles

Format: [type]: [clear imperative title]

---

GitHub issue creation

Standard issue

gh issue create \
  --title "feat: add CSV export to reports" \
  --body "$(cat <<'BODY'
## Problem
Users need to export report data for external analysis. Currently only PDF is supported, which isn't usable in spreadsheets.

## Goal
Users can download any report as CSV in one click.

## Scope
**In:**
- CSV export button on report detail page
- All visible columns included
- Filename: `report-[id]-[date].csv`

**Out:**
- Scheduled/automated exports
- Custom column selection

## Acceptance criteria
- [ ] WHERE a report detail page is shown THE SYSTEM SHALL display an Export button.
- [ ] WHEN a user exports a report THE SYSTEM SHALL produce a valid CSV file with a header row.
- [ ] WHEN a report has 10k+ rows THE SYSTEM SHALL complete the export without timing out.
- [ ] IF a report has no rows THEN THE SYSTEM SHALL download a headers-only CSV.

## Technical notes
**Approach:** Stream response, don't buffer full dataset in memory
**Dependencies:** None
BODY
)" \
  --label "type:feature" \
  --assignee "@me"

Sub-issue (part of epic)

# 1. Create the sub-issue
CHILD_ID=$(gh issue create \
  --title "feat: CSV export — streaming backend endpoint" \
  --body "..." \
  --json number --jq '.number')

# 2. Link it to parent epic #42
gh api repos/{owner}/{repo}/issues/42/sub_issues \
  --method POST \
  -f sub_issue_id=$CHILD_ID

Get {owner}/{repo} from:

gh repo view --json nameWithOwner --jq '.nameWithOwner'

Update existing issue

# Add comment with update
gh issue comment 42 --body "Scope change: removing X, adding Y. See updated description."

# Edit body
gh issue edit 42 --body "$(cat updated-prd.md)"

# Close with reason
gh issue close 42 --comment "Shipped in #87"

---

Local file format (optional)

Use when: no GitHub access, or user explicitly wants local tracking.

PRD file: .agents/memory/[kebab-name].md

Use the PRD structure from above. Add # [Feature Name] as h1. Include a last_verified: YYYY-MM-DD frontmatter field so the memory file stays auditable.

File naming rules:

• kebab-case only: video-generation-with-captions.md
• Full words, no abbreviations: not vid-gen.md
• No dates in filename (use metadata)

---

Sub-issue sizing rules

A sub-issue should:

• Ship in one PR
• Be completable in 1 session (not 5 hours of work)
• Have its own acceptance criteria, independent of siblings
• NOT depend on an unmerged sibling

If you're writing a sub-issue that says "do X after Y is merged" — that's a dependency, list it. Don't assume order.

---

When to push back on requirements

Stop and flag to user if:

• Acceptance criteria can't be tested (too vague)
• Scope includes 3+ unrelated things (split the issue)
• "Out of scope" section is empty on anything >medium complexity
• Breaking change with no migration path defined
• Security-sensitive and no threat model mentioned

---

Quick reference