new-task

name	new-task
description	Initialize a new task — read spec, create branch, implement, merge
version	2.0.0
compat	claude-code, codex, cursor, openclaw

Skill: new-task

Purpose

Initialize a new task from the active epic. The value of this skill is in the order: read first, plan second, implement third.

The most costly agent error is starting to write code before understanding the system's constraints and acceptance criteria.

Context to read first

• AGENT_TASKS.md — full task description and acceptance criteria
• CLAUDE.md — active critical rules for this project
• Specific .knowledge/ files indicated in the task

Preconditions

• On main with recent pull: git checkout main && git pull origin main
• The active epic is marked in AGENT_TASKS.md
• The task has defined acceptance criteria (if not, define them before starting)

Invocation

/new-task [epic]-[task]

Examples:

/new-task E1-T02
/new-task E0-T05

---

Steps

1. Read the task in AGENT_TASKS.md

Read the full task description: what it does, why it exists, and the acceptance criteria.

If acceptance criteria are not defined or are ambiguous, STOP and ask for clarification before creating the branch. Implementing without clear criteria guarantees rework.

Well-defined criteria look like:

Acceptance criteria:
- [ ] `npm run dev` starts without errors
- [ ] The form validates email before submitting
- [ ] Data is persisted in Supabase
- [ ] The user sees a success message after 2 seconds

Poorly defined criteria:

Acceptance criteria:
- [ ] The feature works

2. Read relevant knowledge

Read the .knowledge/ files that CLAUDE.md or the task indicate.

Do not assume you remember content from previous sessions — always read.

Minimum files to read for ANY task:

• CLAUDE.md — stack, critical rules, environment variables
• Any .knowledge/ file the task explicitly mentions

Additional files based on task type:

• Touches the database? → read schema.md or equivalent
• Is UI? → read style-guide.md or design document
• Is integration? → read external integration docs

3. Create the branch

git checkout -b task/E[N]-T[NN]-[short-name]

Convention: task/ + task identifier + short descriptive name (2-3 words, kebab-case).

Examples:

task/E1-T01-auth-flow
task/E2-T03-data-loading
task/E3-T02-form-validation

4. Verify the dev environment works

npm run dev

Or equivalent for your project (yarn dev, pnpm dev, go run, etc.).

If there are startup errors: resolve them before writing new code. Implementing on a broken environment guarantees hours of unnecessary debugging.

Verify that:

• The app starts without errors
• Dev tools work (hot reload, etc.)
• .env variables are configured

5. Implement

With full context and a working environment, implement the task.

Implementation principles:

For web/Node.js projects:

• Business logic goes in lib/ — never in route handlers or components
• Route handlers are thin: extract input → call lib/ → return response
• Each function in lib/ handles errors with typed prefixes (see error contract in CLAUDE.md)
• Commit with /commit after each coherent unit of work — don't accumulate everything for one final commit

For general projects:

• Follow conventions defined in CLAUDE.md and .knowledge/conventions.md
• Don't hardcode credentials, secrets, or contact data
• Validate user input before processing

6. Verify quality before continuing

npm run build    # must pass without errors or warnings
npm run dev      # manually test the main task flow

If the build fails: resolve before advancing. A broken build that accumulates is exponentially harder to debug than one resolved immediately.

7. Create the PR

/pr

The /pr skill handles: verify build, push, create PR, run review, merge.

8. Update status in AGENT_TASKS.md

Change the task status to ✅ (complete) when the PR is merged. Record the PR number in the corresponding field.

---

Validation

The task is correctly initialized if:

• Relevant .knowledge/ files were read BEFORE writing code
• The branch exists with the correct name
• npm run dev starts without errors before implementation begins
• Acceptance criteria were clear before starting

A task is complete when:

• The PR is merged
• ALL acceptance criteria in AGENT_TASKS.md are marked with ✅
• No blockers pending from /review

Common failure modes

Starting implementation without reading .knowledge/. The agent assumes it remembers system constraints from previous sessions. It doesn't. The result is code that violates critical rules and gets blocked by pr-review.

Not verifying npm run dev before implementing. If the environment was already broken before the task, it's impossible to know if new errors are from the task or pre-existing. Always start from a clean environment.

Ambiguous acceptance criteria. Implementing without knowing exactly what "done" means guarantees rework. If criteria say "the UI shows the data", that's ambiguous — all data? what format? with empty state handling? Clarify before implementing, not after.

Accumulating too much in a single commit. Large commits are hard to review and hard to revert. Commit after each coherent unit: a component, a function, a migration. Not at the end of the day.