Single-task intake
Review-first workflow for drafting a single Task from raw input (description, bug report,
email snippet, or ops note), then applying it into planning/tasks/. Complements
epic-authoring.md and epic-decomposition.md.
Flow
input → plan create-task → validate → review → apply draft-task → planning/tasks/<id>.md
Task IDs are allocated at apply time by a2c_core according to .a2c/config.yaml
id_format settings (Jira-like TASK-1 by default, or GitLab-style numeric ids when
configured). An explicit id in --from-task-json is stored on the draft and used at apply
when set.
Commands
| Command | Purpose |
|---|---|
a2c plan create-task | Propose one task draft from raw input (no writes) |
a2c show draft-task-intake <draft-key> | Inspect the cached task draft |
a2c apply draft-task <draft-key> | Write the validated draft into planning/tasks/ |
Epic decomposition drafts still use a2c show draft-task <epic-id> <index>.
Input modes
Provide exactly one input source:
| Flag | Use |
|---|---|
--from-text "..." | Inline description or bug report |
--from-file <path> | Text or Markdown file (e.g. pasted email) |
--from-task-json <path> | Single decomposition-style task object (no LLM); see schemas/task-draft.schema.json |
--stdin | Piped input for automation |
a2c plan create-task --from-text "Add health check endpoint for /api/status"
a2c plan create-task --from-task-json ./task-onboard-impl.json --epic epic-onboarding
echo "User reports 500 on save" | a2c plan create-task --stdin --bug --provider mock
a2c plan create-task --from-file ./support-email.txt --type bug
Task body profiles
Task section contracts live in profiles/task-body/ (feature-minimal, feature-expanded,
bug). Profiles drive validation, composition, and templates. Recorded tasks remain Markdown
with YAML front matter under planning/tasks/.
| Profile | Use |
|---|---|
feature-minimal | Default feature tasks |
feature-expanded | Large AI-driven features |
bug | Bug intake (--type bug) |
Task draft JSON accepts either:
body— monolithic markdown string, orsections— object keyed by profile sectionkey, composed at import
Optional profile selects the contract. See task-body-profiles.md
and schemas/task-draft.schema.json.
Task templates
| Template | Flag | Profile |
|---|---|---|
| Feature / general | default | feature-minimal |
| Large AI-driven feature | --profile feature-expanded or expanded JSON | feature-expanded |
| Bug | --type bug or --bug | bug |
For large or AI-driven features, use the feature-expanded profile so intent and
constraints are not lost between brainstorm and implementation. Canonical example:
- JSON:
tests/fixtures/workflows/task_m9_historical_delivery_metrics.json - Editable body source:
tests/fixtures/workflows/task_m9_historical_delivery_metrics.body.md - Profile:
feature-expanded(M9 body also satisfiesfeature-minimal)
When brainstorming with AI, ask for output matching schemas/task-draft.schema.json
(title, status, optional epic_id, and either body or sections + profile). Edit the
.body.md companion file, sync JSON with scripts/sync_task_fixture_json.py (optionally
--profile feature-expanded --format sections), then preview the applied Markdown with
pytest tests/test_task_m9_markdown_preview.py -v -s.
Optional epic linkage
a2c plan create-task --from-text "Add onboarding tooltip" --epic epic-onboarding
- Validates the epic exists at plan time.
- Sets
epic_idon the task at apply. - Appends the new task id to the epic's
task_idswhen supported.
Providers
Reuses the Milestone 5 provider stack (mock, openai, local, ollama) for text intake.
--from-task-json skips the provider and imports a validated task object directly.
Resolution: --provider > decomposition.provider in config > mock.
Review and apply
a2c plan create-task --from-text "Add health check endpoint" --provider mock \
--fixture tests/fixtures/workflows/create_task_valid.json
a2c show draft-task-intake add-health-check-endpoint
a2c apply draft-task add-health-check-endpoint
Drafts are cached under .a2c/cache/create-task/<draft-key>/.
Guarantees
- Provider output is untrusted until validated.
plannever writes intoplanning/tasks/.- Final task id is allocated at apply only.
applyre-validates and refuses to overwrite unless--force.
Examples
# Simple task
a2c plan create-task --from-text "Add health check endpoint for /api/status"
# Bug from report text
a2c plan create-task --from-text "User reports 500 error when saving profile" --type bug
# From file, linked to epic
a2c plan create-task --from-file ./bug-report.txt --type bug --epic epic-onboarding
# Import one task from epic decomposition JSON (no LLM)
a2c plan create-task --from-task-json ./task-onboard-impl.json
Limitations (first version)
- One input → one task draft per run.
- No email/webhook integration (CLI is automation-friendly via
--stdin). - No multi-task generation (use Epic decomposition for that).