feature

name	feature
description	Feature & chore planning — research codebase, design options, write a structured spec/implementation plan to the project specs directory
metadata	{"phase":"plan","input":"[adw_id] <prompt> — adw_id is optional; prompt is a plain-language description of the feature","output":"path to the written spec file in specs_dir","dependencies":"onboard-project, design-patterns"}

When to trigger

Use this skill when the user:

• asks to plan a feature or chore, or write an implementation plan
• suggests implementing or fixing something and no spec exists yet

Feature & Chore Planning

Generate a structured implementation plan — for a new feature or a chore (fix, refactor, maintenance work with no new user-facing capability) — and save it as a markdown file in the project's specs directory.

Input Arguments

Argument	Description	Example
adw_id	(optional) Unique identifier for the AI Developer Workflow	adw-42
prompt	A plain-language description of the feature to plan	"Add retry logic to the API client"

If prompt is missing or unclear, stop immediately and ask the user to provide it before doing anything else. adw_id is optional — if not provided, omit it from the filename and metadata.

---

Before You Start

Check Argument Validity

• Confirm prompt describes a concrete feature (not a question or vague idea)
• If prompt fails this check, ask the user to clarify before continuing
• adw_id is optional; if not provided, proceed without it

---

Process

Follow these steps in order. Do not skip ahead.

Step 1: Load Project Context

1. If this is a new session and project context is not yet loaded, invoke the onboard-project skill before continuing
   • onboard-project loads project context and # WORKSPACE rules automatically
2. Use context loaded by onboard-project for the research phase

Step 2: Research & Design

1. Load context per # WORKSPACE → Context Loading, matching Tier 1 on Keywords against this feature request — an existing doc may already cover a related or overlapping feature.
2. Create a checklist of everything that needs to be explored.
3. Run sub-tasks in parallel where possible.
4. Wait for all sub-tasks to finish before writing anything.
5. Collect the architectural conventions that bear on this feature — from CLAUDE.md, docs_context, matched core_docs_dir files, and feedback memory (e.g. thin-model, jobs-orchestrate-only). These populate the plan's Conventions to Follow section.
6. Present findings with 2–3 design options, each with clear pros and cons. Note if a matched dictionary entry overlaps with this feature. Get confirmation on the chosen approach before moving to Step 3.
7. If the chosen option is structural — a growing conditional, a new extension point, swappable providers, a boundary to decouple — invoke the design-patterns skill in design mode on it. Add any pattern that survives its fit test to Conventions to Follow as a rule ("payment providers are selected through a strategy interface, not a conditional"), not as a class or method to create. Skip this when the option adds no new structure.

Step 3: Write the Plan

Use specs_dir (default: docs/specs/).

Determine {type}:

• feature — new user-facing capability
• chore — fix, refactor, or maintenance work with no new user-facing capability

Save the file using this naming pattern:

{specs_dir}{unix_timestamp}-{type}-{descriptive-name}.md

If adw_id was provided:

{specs_dir}{unix_timestamp}-{type}-{adw_id}-{descriptive-name}.md

Replace {descriptive-name} with a short, hyphenated name derived from the request (e.g., add-retry-logic, create-workflow-api, fix-nil-publish-job-args).

Step 4: Enumerate Behaviors to Cover

List the behaviors this feature must be tested against — one line each, in plain language, across happy paths, edge cases, error scenarios, and permission/authorization. Skip a category with a one-line reason rather than inventing an entry to fill it.

Write these into the Testing Strategy → Behaviors to Cover section of the plan.

Do not write DSL test cases here. A DSL case requires a confirmed seam (the specific public interface under test), and this plan deliberately does not decide class or method placement — see Constraint 4. Seam-anchored cases are drafted by the implement skill, per phase, once the seam exists. What belongs in the plan is what must hold true, not where it is asserted.

---

Plan Format

# {Feature|Chore}: <name>

## Metadata
- **adw_id:** `{adw_id if provided, otherwise omit this line}`
- **prompt:** `{prompt}`
- **created:** `{timestamp}`

---

## Feature Description
- **Context:** <one bullet — relevant background or current state>
- **Problem:** <one bullet — what's wrong or missing>
- **Solution:** <one bullet — what this plan does about it>

## User Story
As a <type of user>,
I want to <action or goal>,
So that <the benefit or >.




  — 


 


 



 
 

---





  — 



  — 

---




`>
 
 
  — 

---












---






 


 

---








 


 


 


 




---



 [ ] 
 [ ] 

---

---

Notes

<Optional: future considerations, known limitations, required libraries, or dependencies on other features.>

---

## Output

Return the full file path of the created plan, e.g.:

docs/specs/1711234567-feature-add-retry-logic.md docs/specs/1711234567-feature-adw-42-add-retry-logic.md docs/specs/1711234567-chore-fix-nil-publish-job-args.md

---

## Constraints

1. **Resolve everything before writing** — No open questions in the final plan.
2. **Match existing conventions** — Mirror the naming, file organization, and API patterns found in the codebase. Do not prescribe function-level structure (method length, class boundaries, helper extraction) — that's decided at implementation time, not planning time.
3. **Incremental and testable** — Each phase should be shippable and verifiable on its own.
4. **Be specific — about *what* and *where*, not *how*** — Avoid vague tasks like "update the config". Name the file and the behavior that changes. But "where" means file + behavior, NOT layer placement: do not decide model-vs-service-vs-job or invent a specific class/method to add — that is a class-boundary decision (see constraint 2) and must follow the **Conventions to Follow** section, resolved at implementation time. Write "cancel sibling jobs when one fails" (behavior), not "add `PublishClipJob.cancel_siblings` class method" (structure).
5. **Fail loudly** — If a required tool is missing or an argument is invalid, stop and say so clearly.