specdacular 0.7.1 → 0.8.0

package/specdacular/workflows/renumber-phases.md

@@ -1,273 +0,0 @@
-<purpose>
-Renumber all phases to a clean integer sequence after decimal phases have been inserted.
-
-**Key principles:**
-- Always preview and confirm before renaming anything
-- Rename directories highest-to-lowest to avoid collisions
-- Update ALL references: directories, plan frontmatter, ROADMAP.md, STATE.md
-- Remove `(INSERTED)` markers after renumbering
-
-**Output:** Renamed phase directories, updated ROADMAP.md, STATE.md, config.json, plan frontmatter
-</purpose>
-
-<process>
-
-<step name="validate">
-Validate the feature exists and has the required structure.
-
-1. Check feature directory exists:
-```bash
-[ -d ".specd/features/$feature" ] || { echo "Feature not found"; exit 1; }
-```
-
-2. Check plans directory exists:
-```bash
-[ -d ".specd/features/$feature/plans" ] || { echo "No plans directory"; exit 1; }
-```
-
-3. Check ROADMAP.md exists:
-```bash
-[ -f ".specd/features/$feature/ROADMAP.md" ] || { echo "No ROADMAP.md"; exit 1; }
-```
-
-**If feature not found:**
-```
-Feature '{name}' not found.
-
-Available features:
-{list .specd/features/*/}
-```
-</step>
-
-<step name="collect_phases">
-List all phase directories and build the renumbering mapping.
-
-1. List all `phase-*` directories under `plans/`:
-```bash
-ls -d .specd/features/$feature/plans/phase-* 2>/dev/null | sort -V
-```
-
-2. Sort numerically — integers first, then decimals in order:
-   - phase-01, phase-02, phase-03, phase-03.1, phase-03.2, phase-04, phase-05
-   - Use version sort (`sort -V`) to get correct ordering
-
-3. Build mapping: assign sequential integers starting from 01:
-   ```
-   phase-01   → phase-01 (unchanged)
-   phase-02   → phase-02 (unchanged)
-   phase-03   → phase-03 (unchanged)
-   phase-03.1 → phase-04 (renumbered)
-   phase-03.2 → phase-05 (renumbered)
-   phase-04   → phase-06 (renumbered)
-   phase-05   → phase-07 (renumbered)
-   ```
-
-4. Identify which directories actually need renaming (skip unchanged ones)
-
-**If no decimal phases found:**
-```
-No decimal phases found — nothing to renumber.
-
-All phases are already clean integers:
-{list phases}
-```
-Exit workflow.
-</step>
-
-<step name="preview">
-Show the user the renumbering mapping and ask for confirmation.
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PHASE RENUMBERING PREVIEW
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Feature: {feature}
-
-| Current | New | Status |
-|---------|-----|--------|
-| phase-01/ | phase-01/ | unchanged |
-| phase-02/ | phase-02/ | unchanged |
-| phase-03/ | phase-03/ | unchanged |
-| phase-03.1/ | phase-04/ | renumbered |
-| phase-04/ | phase-05/ | renumbered |
-
-Directories to rename: {count}
-Files to update: ROADMAP.md, STATE.md, config.json, plan frontmatter
-```
-
-Use AskUserQuestion:
-- header: "Renumber"
-- question: "Proceed with phase renumbering?"
-- options:
-  - "Yes, renumber" — Continue to rename_directories
-  - "Cancel" — Exit workflow
-
-**If user cancels:** Exit with "Renumbering cancelled. No changes made."
-</step>
-
-<step name="rename_directories">
-Rename phase directories, processing from highest target number down to avoid collisions.
-
-**Why highest-to-lowest?** If we rename phase-03.1 → phase-04 first, it would collide with the existing phase-04. By starting from the highest target number and working down, we avoid this:
-
-1. Build list of renames needed, sorted by target number descending
-2. For each rename (highest first):
-```bash
-mv ".specd/features/$feature/plans/phase-{old}" ".specd/features/$feature/plans/phase-{new}"
-```
-
-Example order:
-```bash
-# Process highest target first to avoid collisions
-mv plans/phase-04/ plans/phase-05/    # 04 → 05 (no collision, 05 doesn't exist)
-mv plans/phase-03.1/ plans/phase-04/  # 03.1 → 04 (no collision, 04 just moved)
-```
-
-3. Skip directories that don't change (e.g., phase-01 → phase-01)
-
-4. Confirm each rename:
-```
-Renamed: phase-{old}/ → phase-{new}/
-```
-</step>
-
-<step name="update_plan_frontmatter">
-Update YAML frontmatter in every plan file under the renamed phases.
-
-1. Find all plan files (`*.md`) in renamed phase directories:
-```bash
-find .specd/features/$feature/plans/ -name "*.md" -type f
-```
-
-2. For each plan file, read and update:
-   - `phase:` field in YAML frontmatter — update to new integer phase number
-   - `depends_on:` paths that reference renamed phases — update phase directory names
-     (e.g., `phase-03.1/01-PLAN.md` → `phase-04/01-PLAN.md`)
-
-3. Only modify files that actually contain references to renamed phases
-
-**Example frontmatter update:**
-```yaml
-# Before:
-phase: "03.1"
-depends_on:
-  - "phase-03/02-PLAN.md"
-
-# After:
-phase: "04"
-depends_on:
-  - "phase-03/02-PLAN.md"  # unchanged — phase-03 didn't move
-```
-
-Also scan plan files in phases that weren't renamed, in case they reference a renamed phase in their `depends_on`.
-</step>
-
-<step name="update_roadmap">
-Rewrite phase headers and references in ROADMAP.md.
-
-1. Read ROADMAP.md
-
-2. For each phase in the mapping that changed:
-   - Update phase headings: `## Phase {old}:` → `## Phase {new}:`
-   - Remove `(INSERTED)` markers from renumbered phases
-   - Update plan references within phase sections (e.g., "Plan 3.1.01" → "Plan 4.01")
-   - Update cross-references to other phases that were renumbered
-
-3. Preserve all other content exactly (descriptions, goals, plan details)
-
-4. Write updated ROADMAP.md
-
-**Example:**
-```markdown
-# Before:
-## Phase 03.1: Architecture Update (INSERTED)
-
-# After:
-## Phase 04: Architecture Update
-```
-</step>
-
-<step name="update_state">
-Rewrite all phase references in STATE.md.
-
-1. Read STATE.md
-
-2. Update ALL phase references throughout the file:
-   - **Stage Progress checkboxes:** `Phase {old}` → `Phase {new}`
-   - **Plan Status table:** Phase column values
-   - **Completed Plans table:** Plan paths containing phase directories
-   - **Current Plan section:** If referencing a renamed phase
-   - **Roadmap Evolution notes:** Update phase numbers in evolution history
-   - **Session Notes:** Any phase references
-
-3. For roadmap evolution, add a note about renumbering:
-```markdown
-- Phases renumbered to clean integer sequence: {mapping summary}
-```
-
-4. Write updated STATE.md
-</step>
-
-<step name="update_config">
-Update config.json with the new phase count.
-
-1. Read config.json
-2. Set `phases_count` to the total number of integer phases (the final count after renumbering)
-3. Write updated config.json
-</step>
-
-<step name="completion">
-Present completion summary:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- PHASES RENUMBERED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Feature: {feature}
-
-**Renames:**
-{For each rename:}
-- phase-{old}/ → phase-{new}/
-
-**Updated files:**
-- ROADMAP.md — Phase headers and references updated
-- STATE.md — All phase references updated
-- config.json — phases_count = {new count}
-- {N} plan files — Frontmatter updated
-
-**Removed markers:** (INSERTED) tags cleaned up
-
-───────────────────────────────────────────────────────
-
-All phases now use clean integer numbering.
-`/specd:phase:execute {feature}` to continue execution.
-```
-
-End workflow.
-</step>
-
-</process>
-
-<safety>
-- Always preview and confirm before any renames
-- Process renames highest-to-lowest to avoid directory collisions
-- Skip directories that don't change
-- Update ALL references across all files before finishing
-- If any rename fails, stop and report — don't leave partial state
-</safety>
-
-<success_criteria>
-Renumbering is complete when:
-
-- [ ] Feature validated with plans and ROADMAP.md
-- [ ] All phase directories collected and sorted correctly
-- [ ] Renumbering mapping previewed and confirmed by user
-- [ ] Directories renamed without collisions (highest-to-lowest)
-- [ ] Plan file frontmatter updated (phase, depends_on references)
-- [ ] ROADMAP.md headers updated, `(INSERTED)` markers removed
-- [ ] STATE.md phase references updated everywhere
-- [ ] config.json `phases_count` set to final integer count
-- [ ] Summary shown to user
-</success_criteria>

package/specdacular/workflows/research-feature.md

@@ -1,252 +0,0 @@
-<purpose>
-Research how to implement a feature by spawning parallel agents for different research dimensions.
-
-Uses three parallel research tracks:
-1. **Codebase Integration** - Claude Code Explore agent investigates existing code
-2. **External Patterns** - General-purpose agent researches libraries, patterns, approaches
-3. **Pitfalls** - General-purpose agent researches what goes wrong
-
-Output: Single synthesized RESEARCH.md that the planner consumes.
-</purpose>
-
-<philosophy>
-
-## Research Serves Planning
-
-Every finding must be actionable. "Use Zustand" is useless. "Use Zustand 4.5+, create store in src/store/{feature}.ts following pattern from src/store/user.ts" is actionable.
-
-## Codebase First
-
-The most valuable research is understanding how this fits with existing code. External patterns matter, but integration patterns matter more.
-
-## Verification Required
-
-Don't trust Claude's training data for library versions or APIs. Verify with Context7 or official docs. Mark unverified findings as LOW confidence.
-
-## Decisions Get Recorded
-
-Any choice made during research (library selection, pattern choice, architecture decision) goes into DECISIONS.md with rationale.
-
-</philosophy>
-
-<research_dimensions>
-
-## Dimension 1: Codebase Integration
-
-**Agent:** Claude Code Explore (subagent_type="Explore")
-**Purpose:** Understand how feature integrates with existing code
-
-**Investigates:**
-- What modules/files to import from
-- What patterns similar features follow
-- Where new files should be created
-- What types/interfaces to reuse
-- What utilities/hooks already exist
-
-**Output format:**
-```markdown
-## Codebase Integration Findings
-
-### Import Dependencies
-- `src/lib/auth.ts` — provides `getSession()`, needed for user context
-- `src/types/user.ts` — provides `User` type, needed for type safety
-
-### Patterns to Follow
-- **API routes:** Follow pattern in `src/app/api/users/route.ts`
-  - Use `getServerSession` for auth
-  - Return `Response.json()` with proper status codes
-  - Validate input with zod
-
-### File Locations
-New files:
-- `src/app/api/{feature}/route.ts` — API endpoint
-- `src/components/{Feature}/index.tsx` — Main component
-- `src/hooks/use{Feature}.ts` — Data hook
-- `src/types/{feature}.ts` — Type definitions
-
-Modify:
-- `src/app/layout.tsx` — Add provider if needed
-
-### Reusable Code
-Types:
-- @src/types/common.ts — `ApiResponse<T>`, `PaginatedResponse<T>`
-
-Utilities:
-- @src/lib/fetcher.ts — `fetcher()` for SWR
-- @src/lib/validation.ts — zod schemas
-
-Components:
-- @src/components/ui/Button — existing button component
-- @src/components/ui/Input — existing input component
-
-### Integration Points
-- Auth: Use `getServerSession` from `@/lib/auth`
-- Database: Use `db` from `@/lib/db`
-- State: Create store in `src/store/` following existing pattern
-```
-
-## Dimension 2: External Patterns
-
-**Agent:** general-purpose with feature-researcher instructions
-**Purpose:** Research standard approaches, libraries, patterns
-
-**Investigates:**
-- Standard libraries for this feature type
-- Architecture patterns that work well
-- Code patterns and examples
-- What NOT to hand-roll
-
-**Tool strategy:**
-1. Context7 first for any library
-2. Official docs via WebFetch
-3. WebSearch with current year
-4. Verify everything
-
-**Output format:**
-```markdown
-## External Patterns Findings
-
-### Standard Stack
-| Library | Version | Purpose | Confidence |
-|---------|---------|---------|------------|
-| zod | 3.22+ | Input validation | HIGH (Context7) |
-| swr | 2.2+ | Data fetching | HIGH (Context7) |
-
-### Architecture Pattern
-**Pattern:** Feature-based modules
-**Why:** Keeps related code together, easier to maintain
-**Structure:**
-```
-src/features/{name}/
-├── api.ts        # API calls
-├── hooks.ts      # React hooks
-├── types.ts      # TypeScript types
-├── components/   # UI components
-└── index.ts      # Public exports
-```
-
-### Code Patterns
-
-**Data fetching with SWR:**
-```typescript
-// Source: Context7 - swr
-export function use{Feature}() {
-  const { data, error, isLoading, mutate } = useSWR<{Feature}[]>(
-    '/api/{feature}',
-    fetcher
-  )
-  return { items: data, error, isLoading, refresh: mutate }
-}
-```
-
-### Don't Hand-Roll
-| Problem | Use Instead | Why |
-|---------|-------------|-----|
-| Form validation | zod + react-hook-form | Edge cases, error messages |
-| Data fetching | SWR or React Query | Caching, revalidation, race conditions |
-| Date formatting | date-fns | Timezone handling, localization |
-```
-
-## Dimension 3: Pitfalls
-
-**Agent:** general-purpose with feature-researcher instructions
-**Purpose:** Research what commonly goes wrong
-
-**Investigates:**
-- Common implementation mistakes
-- Performance pitfalls
-- Security issues
-- Integration gotchas
-
-**Output format:**
-```markdown
-## Pitfalls Findings
-
-### Critical (causes failures/rewrites)
-
-**Race conditions in data fetching**
-- Why it happens: Multiple rapid requests, stale closures
-- Prevention: Use SWR/React Query, they handle this
-- Detection: Data flickers, wrong data after navigation
-
-**Missing auth checks on API routes**
-- Why it happens: Forget to add auth middleware
-- Prevention: Auth check first line of every handler
-- Detection: Unauthenticated access succeeds
-
-### Moderate (causes bugs/debt)
-
-**Type mismatches between API and client**
-- Why it happens: Types defined separately, drift over time
-- Prevention: Single source of truth for types, use zod inference
-- Detection: Runtime errors, TypeScript errors after API changes
-
-### Minor (causes friction)
-
-**Inconsistent error handling**
-- Why it happens: Different patterns in different places
-- Prevention: Create `handleApiError` utility, use everywhere
-- Detection: Error messages vary in format/location
-```
-
-</research_dimensions>
-
-<synthesis>
-
-## Combining Research
-
-After all agents complete, synthesize into RESEARCH.md:
-
-1. **Summary** - Key findings across all dimensions
-2. **Codebase Integration** - Full findings from Explore agent
-3. **Implementation Approach** - External patterns, adapted for this codebase
-4. **Pitfalls** - All pitfalls with task-specific warnings
-5. **Confidence Assessment** - Honest evaluation of each area
-6. **Open Questions** - What couldn't be resolved
-
-## Recording Decisions
-
-During synthesis, identify any decisions that were made:
-
-- Library choice → DEC-XXX with rationale
-- Pattern choice → DEC-XXX with rationale
-- Architecture choice → DEC-XXX with rationale
-
-Add all to DECISIONS.md with:
-- Date
-- Context (from research)
-- Decision
-- Rationale (from findings)
-- Implications (for implementation)
-- References (sources used)
-
-</synthesis>
-
-<quality_gates>
-
-## Before Spawning Agents
-
-- [ ] Feature exists with FEATURE.md
-- [ ] Codebase docs available (.specd/codebase/)
-- [ ] Research dimensions identified
-
-## After Each Agent
-
-- [ ] Findings are specific (file paths, versions, code examples)
-- [ ] Confidence levels assigned
-- [ ] Sources cited
-
-## Before Writing RESEARCH.md
-
-- [ ] All agents completed
-- [ ] Findings synthesized (not just concatenated)
-- [ ] Conflicts resolved
-- [ ] Decisions extracted
-
-## Before Committing
-
-- [ ] RESEARCH.md follows template
-- [ ] DECISIONS.md updated with new decisions
-- [ ] No LOW confidence items presented as recommendations
-
-</quality_gates>