feat(skills): enterprise-analyst rework of authoring skill prompts

agents/anthropic/skills/spec-design/SKILL.md

@@ -5,47 +5,69 @@ description: Draft or revise the design.md document for the active specification
 
 # spec-design
 
-Author the technical design document for the active feature spec.
+Author the technical design for the active feature spec. Act as a senior solutions architect: design the simplest system that satisfies the approved requirements, aligned with how the codebase already works.
 
-## Preconditions
+## Operating principles
+
+- **Investigate before asking.** Most design inputs live in the requirements and the target codebase. Ask the user only about decisions that are genuinely open after you've looked.
+- **Present decisions, not blank questions.** When a material choice is open (framework, storage, integration approach), offer 2–3 options with trade-offs and a recommendation — in one batched message. Decisions the existing stack already dictates: just decide and record the rationale.
+- **MVP first.** Design for the P0 requirements. Note how the design can evolve in Future Considerations instead of building speculative capacity now. Every piece of complexity must be traceable to a requirement ID.
+- **Right-size the document.** Include a section only when it applies. Where it doesn't (e.g. API Design for a CLI tool), keep the heading with one line: `Not applicable — <reason>`. Never fabricate boilerplate to fill a template.
+
+## Step 1 — Preconditions
 
 1. Read active spec: `cat spec/.current-spec`.
-2. Verify requirements are approved: check that `spec/<spec>/.requirements-approved` exists.
-   - If not, tell the user: "Requirements are not approved. Run the `spec-approve` skill with phase `requirements` first." Then stop.
-3. Read `spec/<spec>/requirements.md` fully to understand what is being designed.
+2. Verify requirements are approved: `spec/<spec>/.requirements-approved` exists. If not, tell the user: "Requirements are not approved. Run the `spec-approve` skill with phase `requirements` first." Then stop.
+3. Read `spec/<spec>/requirements.md` fully — the P0 set defines what the design must satisfy.
 4. Read `spec/<spec>/README.md` for spec context.
 
-## Steps
-
-1. If `spec/<spec>/design.md` already exists, read it and make targeted edits via Edit. Do not rewrite blindly.
-2. If it does not exist, create `spec/<spec>/design.md` with these sections:
-   - **Status** — `Draft`
-   - **Architecture Overview** — high-level system diagram (ASCII or mermaid)
-   - **Component Breakdown** — major components, responsibilities, boundaries
-   - **Data Flow** — how data moves through the system
-   - **Technology Stack** — choices with rationale tied back to requirements
-   - **Data Model** — schemas, entities, relationships (ERD where helpful)
-   - **API Design** — endpoints, request/response shapes, auth, errors, versioning
-   - **Security** — threat model, auth/authz, data protection, input sanitization, secrets
-   - **Performance & Scalability** — targets, caching, scaling plan
-   - **Reliability** — error handling, logging/monitoring, recovery
-   - **Deployment Architecture**
-   - **Technical Risks & Mitigations**
-3. If any architectural or technology decisions are unclear from requirements, ASK before writing — do not invent.
-4. Use ASCII art or mermaid for diagrams.
-5. After writing, recommend:
-   - `spec-review` with phase `design` for a self-audit
-   - `spec-approve` with phase `design` when ready
-   - Then `spec-tasks` to decompose into tasks
+## Step 2 — Discover the technical landscape
+
+1. **Explore the target codebase(s).** Architecture and layering, frameworks and versions (from dependency manifests), how similar features are already built, test and deployment setup. Prefer extending existing patterns over introducing new technology — consistency is a design feature.
+2. **Research before proposing.** For any technology you'd introduce or whose current state matters (versions, maturity, licensing, hosting limits), do a quick web check so your options are current, not remembered.
+3. **Sort the decisions.** Split into: (a) dictated by requirements or the existing stack — decide and record; (b) genuinely open — prepare options.
+
+## Step 3 — Settle open decisions
+
+If any material decisions are open, present them to the user now in one batched message — each with 2–3 options, one-line trade-offs, and your recommendation. Wait for answers before writing. If nothing is open, say what you decided and why, and proceed.
+
+## Step 4 — Write or revise design.md
+
+If `spec/<spec>/design.md` exists: read it and apply targeted Edits — do not rewrite blindly.
+
+If it does not exist, create it with this structure:
+
+- **Header** — `# Design — <spec-id>` followed by `**Status:** Draft · **Created:** <YYYY-MM-DD>`
+- **Overview** — 3–5 sentences: what is being built and the architectural approach in plain words.
+- **Architecture** — a diagram (mermaid or ASCII) plus a component breakdown: each component's responsibility and boundary, and where it lives in the existing codebase.
+- **Design Decisions** — the record that outlives the chat: for each material decision, the options considered, the choice, and why (one short entry each — a table works well).
+- **Data Model** — entities, schemas, relationships (ERD where helpful), validation rules, migration approach if data exists. *(if applicable)*
+- **API & Interfaces** — endpoints or module contracts: request/response shapes, auth, error semantics, versioning stance. *(if applicable)*
+- **Data Flow** — the key user/system flows end to end, referencing the components above.
+- **Security** — the threat surface this feature actually has: auth/authz, input validation, data protection, secrets handling. Not generic OWASP boilerplate.
+- **Performance** — concrete, MVP-realistic targets for the dimensions that matter; caching or optimization only where a requirement demands it.
+- **Reliability & Operations** — error handling strategy, logging/monitoring, deployment shape, rollback.
+- **Future Considerations** — what the MVP defers (from requirements' Future Iterations plus design-level deferrals) and how the current design leaves the door open.
+- **Risks & Mitigations** — technical risks with a concrete mitigation or an explicit acceptance.
 
 ## Quality bar
 
-- Every technology choice has a justification.
-- Every external dependency or integration is explicit.
-- The threat model addresses the actual surface area, not generic OWASP boilerplate.
-- Performance targets are numeric, not "fast".
+- Every technology choice is justified against a requirement or an existing codebase convention — no résumé-driven design.
+- The design is the simplest one that satisfies every P0 requirement; anything beyond that cites the requirement that demands it.
+- Performance and reliability targets are numeric, not "fast" or "robust".
+- Sections marked not-applicable carry a reason.
+- A competent developer who never saw this conversation could implement from this document alone.
+
+## Step 5 — Hand off
+
+Report the file path, the open decisions you settled (and how), and any assumptions needing confirmation. Recommend:
+
+- `spec-review` with phase `design` for a self-audit
+- `spec-approve` with phase `design` when ready
+- Then `spec-tasks` to decompose into tasks
 
 ## Notes
 
-- Use the Write tool for creation, Edit for revisions.
+- Use Write for creation, Edit for revisions.
 - This skill is for code-producing specs only. Research specs use `spec-research`.
+- Do not approve the phase from this skill.

agents/anthropic/skills/spec-implement/SKILL.md

@@ -5,15 +5,16 @@ description: Begin or continue implementation of an approved spec's tasks — se
 
 # spec-implement
 
-Drive implementation of the active spec's task list across target repositories.
+Drive implementation of the active spec's task list across target repositories. Act as a senior developer pairing with a tester: follow the codebase's conventions, verify each task before marking it done, and keep the task list truthful.
 
 ## Preconditions
 
 1. Read active spec: `cat spec/.current-spec`.
 2. Verify tasks approved: check that `spec/<spec>/.tasks-approved` exists.
    - If not, tell the user: "Tasks are not approved. Run the `spec-approve` skill with phase `tasks` first." Then stop.
-3. Read `spec/<spec>/requirements.md` to identify target repositories.
-4. Read `spec/<spec>/tasks.md` to load the task list.
+3. Read `spec/<spec>/requirements.md` to identify target repositories and acceptance criteria.
+4. Read `spec/<spec>/design.md` — the architecture, decisions, and contracts you are implementing against.
+5. Read `spec/<spec>/tasks.md` to load the task list.
 
 ## Step 1 — Identify target repositories
 
@@ -43,7 +44,11 @@ If no repositories are referenced, ask the user where implementation should happ
 - If creating new, ask whether to branch from current or from main, and how to handle any uncommitted changes (stash / commit-and-push).
 - Create the branch accordingly.
 
-## Step 3 — Status display
+## Step 3 — Orient in the codebase
+
+Before the first task in each repo, spend a few minutes orienting: how the code is laid out, naming and error-handling conventions, how tests are written and run (test command, framework), and any lint/format tooling. Match what you find — implementation should look like it was written by the team.
+
+## Step 4 — Status display
 
 Show the user:
 - Spec ID and name
@@ -54,26 +59,27 @@ Show the user:
 
 If the user gave a phase argument (e.g. "phase 2"), focus on that phase only.
 
-## Step 4 — Work through tasks
+## Step 5 — Work through tasks
 
 For each task in order within the current phase:
 
-1. Show the task details and any subtasks.
-2. Identify which target repository the task affects.
-3. Implement the task in that repository.
-4. After completing, update `tasks.md` in the SPEC repo: flip `- [ ]` to `- [x]` (use Edit, do not rewrite the whole file).
-5. Suggest committing in the target repo when a logical unit of work is done.
-6. Move to the next task.
+1. Show the task, its subtasks, and its `Done when:` criterion. Re-read the design section it implements.
+2. Identify which target repository the task affects and locate the relevant code area.
+3. Implement the task following the conventions found in Step 3.
+4. Verify: add or update tests for the change, run the test suite (and lint if configured), and check the task's done criterion holds. If verification fails, fix before proceeding — do not mark a failing task done.
+5. Update `tasks.md` in the SPEC repo: flip `- [ ]` to `- [x]` (use Edit, do not rewrite the whole file).
+6. Suggest committing in the target repo when a logical unit of work is done, with a message referencing the task ID.
+7. Move to the next task.
 
 ## Guidelines
 
 - Work tasks sequentially within a phase. Complete Phase N before starting Phase N+1.
-- Update checkboxes IMMEDIATELY after each task completes — do not batch updates.
-- Commit in the target repo with descriptive messages tied to the task ID where possible.
+- Update checkboxes IMMEDIATELY after each task verifies — do not batch updates, and never flip a checkbox on unverified work.
 - If blocked, note the blocker in tasks.md (a sub-bullet under the task) and move on.
 - If the user is using a tracker, the `spec-update-task` skill (or `spec-sync`) propagates checkbox changes.
 
 ## Notes
 
 - Keep spec repo and target repos in sync; don't let task-completion drift from actual code state.
 - If a task reveals the design was wrong, stop and surface it — don't silently reshape the work. The user may need to revise the design.
+- Prefer the simplest implementation that satisfies the task's done criterion — MVP discipline applies to code, not just documents.

agents/anthropic/skills/spec-new/SKILL.md

@@ -9,30 +9,37 @@ Create a new specification directory under `spec/` and set it as the active spec
 
 ## Inputs to collect
 
-- **Feature name** — short kebab-case (e.g. `user-auth`, `payment-flow`). If the user gave a name in their message, use it verbatim. Otherwise ask once for the name before proceeding.
+- **Feature name** — short kebab-case (e.g. `user-auth`, `payment-flow`). If the user gave a name, use it verbatim. If they described the feature but gave no name, propose a kebab-case name derived from the description and confirm it in the same message as any other question. Otherwise ask once.
+- **Spec type** — `feature` (ships code, goes through design → tasks → implementation) or `research` (ships a decision, goes through research). Infer from the user's phrasing ("research", "evaluate", "compare" → research); if genuinely ambiguous, ask in the same message as the name.
+- **One-line summary** — what this spec is about, in the user's words. Take it from their message; only ask if they gave nothing to work with.
+
+Batch any questions into a single message. Do not invent feature context.
 
 ## Steps
 
 1. Gather context with bash:
    - `ls spec/ 2>/dev/null || echo "No spec directory"` — see existing specs
    - `date +%Y-%m-%d` — today's date for the README
-2. Determine the next sequential ID by scanning the existing spec directories. IDs are zero-padded 3-digit numbers (`001`, `002`, …). The next ID is `max(existing) + 1`. If `spec/` doesn't exist, start at `001`.
-3. Create the directory `spec/<ID>-<feature-name>/` with `mkdir -p`.
-4. Write `spec/.current-spec` containing the new spec directory name (just `<ID>-<feature-name>`, no trailing newline beyond what the editor adds).
-5. Create `spec/<ID>-<feature-name>/README.md` with:
+2. Check for overlap: if an existing spec directory clearly covers the same feature, surface it and ask whether to switch to it (`spec-switch`) instead of creating a duplicate.
+3. Determine the next sequential ID by scanning the existing spec directories. IDs are zero-padded 3-digit numbers (`001`, `002`, …). The next ID is `max(existing) + 1`. If `spec/` doesn't exist, start at `001`.
+4. Create the directory `spec/<ID>-<feature-name>/` with `mkdir -p`.
+5. Write `spec/.current-spec` containing the new spec directory name (just `<ID>-<feature-name>`, no trailing newline beyond what the editor adds).
+6. Create `spec/<ID>-<feature-name>/README.md` with:
    - `# <ID>-<feature-name>` title
+   - The one-line summary
    - `**Created:** <today's date>` line
+   - `**Type:** Feature` (or `Research`) line
    - `**Status:** Draft` line
-   - A phase checklist:
+   - A phase checklist matching the type:
      ```
      - [ ] Requirements
-     - [ ] Design (or Research, for research specs)
-     - [ ] Tasks
-     - [ ] Implementation
+     - [ ] Design          ← feature specs   |   - [ ] Research   ← research specs
+     - [ ] Tasks           ← feature specs only
+     - [ ] Implementation  ← feature specs only
      ```
    - A "Next step" line: `Run the spec-requirements skill to draft requirements.`
-6. Report to the user:
-   - The new spec ID and directory path
+7. Report to the user:
+   - The new spec ID, type, and directory path
    - That it is now the active spec
    - The recommended next step: draft requirements via the `spec-requirements` skill