feat: deploy — email/password only auth, no OAuth buttons

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

.claude/commands/sp.adr.md

@@ -0,0 +1,207 @@
+---
+description: Review planning artifacts for architecturally significant decisions and create ADRs.
+---
+
+# COMMAND: Analyze planning artifacts and document architecturally significant decisions as ADRs
+
+## CONTEXT
+
+The user has completed feature planning and needs to:
+
+- Identify architecturally significant technical decisions from plan.md
+- Document these decisions as Architecture Decision Records (ADRs)
+- Ensure team alignment on technical approach before implementation
+- Create a permanent, reviewable record of why decisions were made
+
+Architecture Decision Records capture decisions that:
+
+- Impact how engineers write or structure software
+- Have notable tradeoffs or alternatives
+- Will likely be questioned or revisited later
+
+**User's additional input:**
+
+$ARGUMENTS
+
+## YOUR ROLE
+
+Act as a senior software architect with expertise in:
+
+- Technical decision analysis and evaluation
+- System design patterns and tradeoffs
+- Enterprise architecture documentation
+- Risk assessment and consequence analysis
+
+## OUTPUT STRUCTURE (with quick flywheel hooks)
+
+Execute this workflow in 6 sequential steps. At Steps 2 and 4, apply lightweight Analyze→Measure checks:
+ - Analyze: Identify likely failure modes, specifically:
+     - Over-granular ADRs: ADRs that document decisions which are trivial, low-impact, or do not affect architectural direction (e.g., naming conventions, minor refactorings).
+     - Missing alternatives: ADRs that do not list at least one alternative approach considered.
+ - Measure: Apply the following checklist grader (PASS only if all are met):
+     - The ADR documents a decision that clusters related changes or impacts multiple components (not a trivial/single-file change).
+     - The ADR explicitly lists at least one alternative approach, with rationale.
+     - The ADR includes clear pros and cons for the chosen approach and alternatives.
+     - The ADR is concise but sufficiently detailed for future reference.
+
+## Step 1: Load Planning Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS.
+
+Derive absolute paths:
+
+- PLAN = FEATURE_DIR/plan.md (REQUIRED - abort if missing with "Run /sp.plan first")
+- RESEARCH = FEATURE_DIR/research.md (if exists)
+- DATA_MODEL = FEATURE_DIR/data-model.md (if exists)
+- CONTRACTS_DIR = FEATURE_DIR/contracts/ (if exists)
+
+## Step 2: Extract Architectural Decisions (Analyze)
+
+Load plan.md and available artifacts. Extract architecturally significant decisions as **decision clusters** (not atomic choices):
+
+**✅ GOOD (Clustered):**
+
+- "Frontend Stack" (Next.js + Tailwind + Vercel as integrated solution)
+- "Authentication Approach" (JWT strategy + Auth0 + session handling)
+- "Data Architecture" (PostgreSQL + Redis caching + migration strategy)
+
+**❌ BAD (Over-granular):**
+
+- Separate ADRs for Next.js, Tailwind, and Vercel
+- Separate ADRs for each library choice
+
+**Clustering Rules:**
+
+- Group technologies that work together and would likely change together
+- Separate only if decisions are independent and could diverge
+- Example: Frontend stack vs Backend stack = 2 ADRs (can evolve independently)
+- Example: Next.js + Tailwind + Vercel = 1 ADR (integrated, change together)
+
+For each decision cluster, note: what was decided, why, where in docs.
+
+## Step 3: Check Existing ADRs
+
+Scan `history/adr/` directory. For each extracted decision:
+
+- If covered by existing ADR → note reference
+- If conflicts with existing ADR → flag conflict
+- If not covered → mark as ADR candidate
+
+## Step 4: Apply Significance Test (Measure)
+
+For each ADR candidate, test:
+
+- Does it impact how engineers write/structure software?
+- Are there notable tradeoffs or alternatives?
+- Will it be questioned or revisited later?
+
+Only proceed with ADRs that pass ALL three tests.
+
+## Step 5: Create ADRs (Improve)
+
+For each qualifying decision cluster:
+
+1. Generate concise title reflecting the cluster (e.g., "Frontend Technology Stack" not "Use Next.js")
+2. Run `create-adr.sh "<title>"` from repo root
+3. Parse JSON response for `adr_path` and `adr_id`
+4. Read created file (contains template with {{PLACEHOLDERS}})
+5. Fill ALL placeholders:
+   - `{{TITLE}}` = decision cluster title
+   - `{{STATUS}}` = "Proposed" or "Accepted"
+   - `{{DATE}}` = today (YYYY-MM-DD)
+   - `{{CONTEXT}}` = situation, constraints leading to decision cluster
+   - `{{DECISION}}` = list ALL components of cluster (e.g., "Framework: Next.js 14, Styling: Tailwind CSS v3, Deployment: Vercel")
+   - `{{CONSEQUENCES}}` = outcomes, tradeoffs, risks for the integrated solution
+   - `{{ALTERNATIVES}}` = alternative clusters (e.g., "Remix + styled-components + Cloudflare")
+   - `{{REFERENCES}}` = plan.md, research.md, data-model.md
+6. Save file
+
+## Step 6: Report Completion
+
+Output:
+
+```
+✅ ADR Review Complete - Created N ADRs, referenced M existing
+```
+
+List created ADRs with ID and title.
+
+If conflicts detected:
+
+```
+⚠️ Conflicts with existing ADRs [IDs]. Review and update outdated decisions or revise plan.
+```
+
+If create-adr.sh fails: Report script error and skip that ADR.
+
+## FORMATTING REQUIREMENTS
+
+Present results in this exact structure:
+
+```
+✅ ADR Review Complete
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📋 Created ADRs: {count}
+   - ADR-{id}: {title}
+   - ADR-{id}: {title}
+
+📚 Referenced Existing: {count}
+   - ADR-{id}: {title}
+
+⚠️  Conflicts Detected: {count}
+   - ADR-{id}: {conflict description}
+
+Next Steps:
+→ Resolve conflicts before proceeding to /sp.tasks
+→ Review created ADRs with team
+→ Update plan.md if needed
+
+Acceptance Criteria (PASS only if all true)
+- Decisions are clustered (not atomic), with explicit alternatives and tradeoffs
+- Consequences cover both positive and negative outcomes
+- References link back to plan and related docs
+```
+
+## ERROR HANDLING
+
+If plan.md missing:
+
+- Display: "❌ Error: plan.md not found. Run /sp.plan first to generate planning artifacts."
+- Exit gracefully without creating any ADRs
+
+If create-adr.sh fails:
+
+- Display exact error message
+- Skip that ADR and continue with others
+- Report partial completion at end
+
+## TONE
+
+Be thorough, analytical, and decision-focused. Emphasize the "why" behind each decision and its long-term implications.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.analyze.md

@@ -0,0 +1,210 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/sp.tasks` has successfully produced a complete `tasks.md`.
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/sp.analyze`.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+
+- SPEC = FEATURE_DIR/spec.md
+- PLAN = FEATURE_DIR/plan.md
+- TASKS = FEATURE_DIR/tasks.md
+
+Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only the minimal necessary context from each artifact:
+
+**From spec.md:**
+
+- Overview/Context
+- Functional Requirements
+- Non-Functional Requirements
+- User Stories
+- Edge Cases (if present)
+
+**From plan.md:**
+
+- Architecture/stack choices
+- Data Model references
+- Phases
+- Technical constraints
+
+**From tasks.md:**
+
+- Task IDs
+- Descriptions
+- Phase grouping
+- Parallel markers [P]
+- Referenced file paths
+
+**From constitution:**
+
+- Load `.specify/memory/constitution.md` for principle validation
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`)
+- **User story/action inventory**: Discrete user actions with acceptance criteria
+- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases)
+- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+
+#### A. Duplication Detection
+
+- Identify near-duplicate requirements
+- Mark lower-quality phrasing for consolidation
+
+#### B. Ambiguity Detection
+
+- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria
+- Flag unresolved placeholders (TODO, TKTK, ???, `<placeholder>`, etc.)
+
+#### C. Underspecification
+
+- Requirements with verbs but missing object or measurable outcome
+- User stories missing acceptance criteria alignment
+- Tasks referencing files or components not defined in spec/plan
+
+#### D. Constitution Alignment
+
+- Any requirement or plan element conflicting with a MUST principle
+- Missing mandated sections or quality gates from constitution
+
+#### E. Coverage Gaps
+
+- Requirements with zero associated tasks
+- Tasks with no mapped requirement/story
+- Non-functional requirements not reflected in tasks (e.g., performance, security)
+
+#### F. Inconsistency
+
+- Terminology drift (same concept named differently across files)
+- Data entities referenced in plan but absent in spec (or vice versa)
+- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note)
+- Conflicting requirements (e.g., one requires Next.js while other specifies Vue)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality
+- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion
+- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case
+- **LOW**: Style/wording improvements, minor redundancy not affecting execution order
+
+### 6. Produce Compact Analysis Report
+
+Output a Markdown report (no file writes) with the following structure:
+
+## Specification Analysis Report
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+
+(Add one row per finding; generate stable IDs prefixed by category initial.)
+
+**Coverage Summary Table:**
+
+| Requirement Key | Has Task? | Task IDs | Notes |
+|-----------------|-----------|----------|-------|
+
+**Constitution Alignment Issues:** (if any)
+
+**Unmapped Tasks:** (if any)
+
+**Metrics:**
+
+- Total Requirements
+- Total Tasks
+- Coverage % (requirements with >=1 task)
+- Ambiguity Count
+- Duplication Count
+- Critical Issues Count
+
+### 7. Provide Next Actions
+
+At end of report, output a concise Next Actions block:
+
+- If CRITICAL issues exist: Recommend resolving before `/sp.implement`
+- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
+- Provide explicit command suggestions: e.g., "Run /sp.specify with refinement", "Run /sp.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'"
+
+### 8. Offer Remediation
+
+Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+## Operating Principles
+
+### Context Efficiency
+
+- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
+- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis
+- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow
+- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
+
+### Analysis Guidelines
+
+- **NEVER modify files** (this is read-only analysis)
+- **NEVER hallucinate missing sections** (if absent, report them accurately)
+- **Prioritize constitution violations** (these are always CRITICAL)
+- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
+- **Report zero issues gracefully** (emit success report with coverage statistics)
+
+## Context
+
+$ARGUMENTS
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.checklist.md

@@ -0,0 +1,320 @@
+---
+description: Generate a custom checklist for the current feature based on user requirements.
+---
+
+## Checklist Purpose: "Unit Tests for English"
+
+**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing**:
+
+- ❌ NOT "Verify the button clicks correctly"
+- ❌ NOT "Test error handling works"
+- ❌ NOT "Confirm the API returns 200"
+- ❌ NOT checking if code/implementation matches the spec
+
+**FOR requirements quality validation**:
+
+- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness)
+- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
+- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency)
+- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage)
+- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases)
+
+**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works.
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Execution Steps
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS list.
+   - All file paths must be absolute.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST:
+   - Be generated from the user's phrasing + extracted signals from spec/plan/tasks
+   - Only ask about information that materially changes checklist content
+   - Be skipped individually if already unambiguous in `$ARGUMENTS`
+   - Prefer precision over breadth
+
+   Generation algorithm:
+   1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts").
+   2. Cluster signals into candidate focus areas (max 4) ranked by relevance.
+   3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit.
+   4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria.
+   5. Formulate questions chosen from these archetypes:
+      - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?")
+      - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?")
+      - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?")
+      - Audience framing (e.g., "Will this be used by the author only or peers during PR review?")
+      - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?")
+      - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?")
+
+   Question formatting rules:
+   - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters
+   - Limit to A–E options maximum; omit table if a free-form answer is clearer
+   - Never ask the user to restate what they already said
+   - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope."
+
+   Defaults when interaction impossible:
+   - Depth: Standard
+   - Audience: Reviewer (PR) if code-related; Author otherwise
+   - Focus: Top 2 relevance clusters
+
+   Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more.
+
+3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers:
+   - Derive checklist theme (e.g., security, review, deploy, ux)
+   - Consolidate explicit must-have items mentioned by user
+   - Map focus selections to category scaffolding
+   - Infer any missing context from spec/plan/tasks (do NOT hallucinate)
+
+4. **Load feature context**: Read from FEATURE_DIR:
+   - spec.md: Feature requirements and scope
+   - plan.md (if exists): Technical details, dependencies
+   - tasks.md (if exists): Implementation tasks
+
+   **Context Loading Strategy**:
+   - Load only necessary portions relevant to active focus areas (avoid full-file dumping)
+   - Prefer summarizing long sections into concise scenario/requirement bullets
+   - Use progressive disclosure: add follow-on retrieval only if gaps detected
+   - If source docs are large, generate interim summary items instead of embedding raw text
+
+5. **Generate checklist** - Create "Unit Tests for Requirements":
+   - Create `FEATURE_DIR/checklists/` directory if it doesn't exist
+   - Generate unique checklist filename:
+     - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`)
+     - Format: `[domain].md`
+     - If file exists, append to existing file
+   - Number items sequentially starting from CHK001
+   - Each `/sp.checklist` run creates a NEW file (never overwrites existing checklists)
+
+   **CORE PRINCIPLE - Test the Requirements, Not the Implementation**:
+   Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for:
+   - **Completeness**: Are all necessary requirements present?
+   - **Clarity**: Are requirements unambiguous and specific?
+   - **Consistency**: Do requirements align with each other?
+   - **Measurability**: Can requirements be objectively verified?
+   - **Coverage**: Are all scenarios/edge cases addressed?
+
+   **Category Structure** - Group items by requirement quality dimensions:
+   - **Requirement Completeness** (Are all necessary requirements documented?)
+   - **Requirement Clarity** (Are requirements specific and unambiguous?)
+   - **Requirement Consistency** (Do requirements align without conflicts?)
+   - **Acceptance Criteria Quality** (Are success criteria measurable?)
+   - **Scenario Coverage** (Are all flows/cases addressed?)
+   - **Edge Case Coverage** (Are boundary conditions defined?)
+   - **Non-Functional Requirements** (Performance, Security, Accessibility, etc. - are they specified?)
+   - **Dependencies & Assumptions** (Are they documented and validated?)
+   - **Ambiguities & Conflicts** (What needs clarification?)
+
+   **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**:
+
+   ❌ **WRONG** (Testing implementation):
+   - "Verify landing page displays 3 episode cards"
+   - "Test hover states work on desktop"
+   - "Confirm logo click navigates home"
+
+   ✅ **CORRECT** (Testing requirements quality):
+   - "Are the exact number and layout of featured episodes specified?" [Completeness]
+   - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity]
+   - "Are hover state requirements consistent across all interactive elements?" [Consistency]
+   - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage]
+   - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases]
+   - "Are loading states defined for asynchronous episode data?" [Completeness]
+   - "Does the spec define visual hierarchy for competing UI elements?" [Clarity]
+
+   **ITEM STRUCTURE**:
+   Each item should follow this pattern:
+   - Question format asking about requirement quality
+   - Focus on what's WRITTEN (or not written) in the spec/plan
+   - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.]
+   - Reference spec section `[Spec §X.Y]` when checking existing requirements
+   - Use `[Gap]` marker when checking for missing requirements
+
+   **EXAMPLES BY QUALITY DIMENSION**:
+
+   Completeness:
+   - "Are error handling requirements defined for all API failure modes? [Gap]"
+   - "Are accessibility requirements specified for all interactive elements? [Completeness]"
+   - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"
+
+   Clarity:
+   - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
+   - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
+   - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"
+
+   Consistency:
+   - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
+   - "Are card component requirements consistent between landing and detail pages? [Consistency]"
+
+   Coverage:
+   - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
+   - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
+   - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"
+
+   Measurability:
+   - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
+   - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"
+
+   **Scenario Classification & Coverage** (Requirements Quality Focus):
+   - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios
+   - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?"
+   - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]"
+   - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]"
+
+   **Traceability Requirements**:
+   - MINIMUM: ≥80% of items MUST include at least one traceability reference
+   - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]`
+   - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"
+
+   **Surface & Resolve Issues** (Requirements Quality Problems):
+   Ask questions about the requirements themselves:
+   - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]"
+   - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]"
+   - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]"
+   - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]"
+   - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]"
+
+   **Content Consolidation**:
+   - Soft cap: If raw candidate items > 40, prioritize by risk/impact
+   - Merge near-duplicates checking the same requirement aspect
+   - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]"
+
+   **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test:
+   - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
+   - ❌ References to code execution, user actions, system behavior
+   - ❌ "Displays correctly", "works properly", "functions as expected"
+   - ❌ "Click", "navigate", "render", "load", "execute"
+   - ❌ Test cases, test plans, QA procedures
+   - ❌ Implementation details (frameworks, APIs, algorithms)
+
+   **✅ REQUIRED PATTERNS** - These test requirements quality:
+   - ✅ "Are [requirement type] defined/specified/documented for [scenario]?"
+   - ✅ "Is [vague term] quantified/clarified with specific criteria?"
+   - ✅ "Are requirements consistent between [section A] and [section B]?"
+   - ✅ "Can [requirement] be objectively measured/verified?"
+   - ✅ "Are [edge cases/scenarios] addressed in requirements?"
+   - ✅ "Does the spec define [missing aspect]?"
+
+6. **Structure Reference**: Generate the checklist following the canonical template in `.specify/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### <requirement item>` lines with globally incrementing IDs starting at CHK001.
+
+7. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize:
+   - Focus areas selected
+   - Depth level
+   - Actor/timing
+   - Any explicit user-specified must-have items incorporated
+
+**Important**: Each `/sp.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows:
+
+- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`)
+- Simple, memorable filenames that indicate checklist purpose
+- Easy identification and navigation in the `checklists/` folder
+
+To avoid clutter, use descriptive types and clean up obsolete checklists when done.
+
+## Example Checklist Types & Sample Items
+
+**UX Requirements Quality:** `ux.md`
+
+Sample items (testing the requirements, NOT the implementation):
+
+- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]"
+- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]"
+- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]"
+- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]"
+- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]"
+
+**API Requirements Quality:** `api.md`
+
+Sample items:
+
+- "Are error response formats specified for all failure scenarios? [Completeness]"
+- "Are rate limiting requirements quantified with specific thresholds? [Clarity]"
+- "Are authentication requirements consistent across all endpoints? [Consistency]"
+- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]"
+- "Is versioning strategy documented in requirements? [Gap]"
+
+**Performance Requirements Quality:** `performance.md`
+
+Sample items:
+
+- "Are performance requirements quantified with specific metrics? [Clarity]"
+- "Are performance targets defined for all critical user journeys? [Coverage]"
+- "Are performance requirements under different load conditions specified? [Completeness]"
+- "Can performance requirements be objectively measured? [Measurability]"
+- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]"
+
+**Security Requirements Quality:** `security.md`
+
+Sample items:
+
+- "Are authentication requirements specified for all protected resources? [Coverage]"
+- "Are data protection requirements defined for sensitive information? [Completeness]"
+- "Is the threat model documented and requirements aligned to it? [Traceability]"
+- "Are security requirements consistent with compliance obligations? [Consistency]"
+- "Are security failure/breach response requirements defined? [Gap, Exception Flow]"
+
+## Anti-Examples: What NOT To Do
+
+**❌ WRONG - These test implementation, not requirements:**
+
+```markdown
+- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001]
+- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003]
+- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010]
+- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005]
+```
+
+**✅ CORRECT - These test requirements quality:**
+
+```markdown
+- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001]
+- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003]
+- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010]
+- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005]
+- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap]
+- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001]
+```
+
+**Key Differences:**
+
+- Wrong: Tests if the system works correctly
+- Correct: Tests if the requirements are written correctly
+- Wrong: Verification of behavior
+- Correct: Validation of requirement quality
+- Wrong: "Does it do X?"
+- Correct: "Is X clearly specified?"
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.clarify.md

@@ -0,0 +1,207 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+handoffs: 
+  - label: Build Technical Plan
+    agent: sp.plan
+    prompt: Create a plan for the spec. I am building with...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/sp.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/sp.specify` or verify feature branch environment.
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 10 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+    - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+    - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+    - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+    - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+    - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions:
+       - **Analyze all options** and determine the **most suitable option** based on:
+          - Best practices for the project type
+          - Common patterns in similar implementations
+          - Risk reduction (security, performance, maintainability)
+          - Alignment with any explicit project goals or constraints visible in the spec
+       - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
+       - Format as: `**Recommended:** Option [X] - <reasoning>`
+       - Then render all options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> (add D/E as needed up to 5) |
+       | Short | Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate) |
+
+       - After the table, add: `You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.`
+    - For short‑answer style (no meaningful discrete options):
+       - Provide your **suggested answer** based on best practices and context.
+       - Format as: `**Suggested:** <your proposed answer> - <brief reasoning>`
+       - Then output: `Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.`
+    - After the user answers:
+       - If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
+       - Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
+       - If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       - Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       - All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       - User signals completion ("done", "good", "no more"), OR
+       - You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       - Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       - Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       - Functional ambiguity → Update or add a bullet in Functional Requirements.
+       - User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       - Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       - Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       - Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       - Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/sp.plan` or run `/sp.clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/sp.specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+- If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+- If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.constitution.md

@@ -0,0 +1,108 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+handoffs: 
+  - label: Build Specification
+    agent: sp.specify
+    prompt: Implement the feature specification based on the updated constitution. I want to build...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     - MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     - MINOR: New principle/section added or materially expanded guidance.
+     - PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.git.commit_pr.md

@@ -0,0 +1,328 @@
+---
+description: An autonomous Git agent that intelligently executes git workflows. Your task is to intelligently executes git workflows to commit the work and create PR.
+---
+
+Your task is to intelligently executes git workflows to commit the work and create PR following your Principles
+
+# Agentic Git Workflow Agent
+
+## Core Principle
+
+You are an autonomous Git agent. Your job is to **fulfill the user's intent efficiently**. You have agency to:
+- Analyze the current state independently
+- Make intelligent decisions about the best workflow
+- Execute steps without asking permission for each one
+- Invoke the human validator only when the decision requires their judgment
+
+The human is not a step-orchestrator. The human is an **intent-provider** and **decision validator**.
+
+## Your Agency
+
+You can autonomously:
+✅ Analyze repository state  
+✅ Determine optimal branch strategy  
+✅ Generate meaningful commit messages based on code changes  
+✅ Create branches, commits, and push to remote  
+✅ Create PRs with intelligent titles and descriptions  
+✅ Detect and handle common errors  
+
+You CANNOT autonomously:
+❌ Run long-running processes (servers, watchers, etc.)  
+❌ Execute code that blocks indefinitely  
+❌ Make changes outside the repo (create files elsewhere, etc.)  
+❌ Execute destructive commands without explicit approval  
+
+You invoke the human when:
+🔴 The intent is ambiguous  
+🔴 Multiple equally-valid strategies exist and you need to know their preference  
+🔴 You detect something risky or unexpected  
+🔴 The outcome differs significantly from what was requested  
+🔴 Any non-Git command would run indefinitely or block execution  
+
+## Phase 1: Context Gathering (Autonomous)
+
+Start by understanding the complete situation:
+
+```bash
+git --version                        # Verify Git exists
+git rev-parse --is-inside-work-tree  # Verify we're in a repo
+git status --porcelain               # See what changed
+git diff --stat                      # Quantify changes
+git log --oneline -5                 # Recent history context
+git rev-parse --abbrev-ref HEAD      # Current branch
+git remote -v                        # Remote configuration
+```
+
+**CRITICAL:** Only run Git commands. Do not:
+- Run `python main.py`, `npm start`, `make`, or other build/start scripts
+- Execute anything that might be long-running or blocking
+- Run tests, servers, or development tools
+
+If Git is not available or this isn't a repo, **invoke human validator** with the problem.
+
+## Phase 2: Analyze & Decide (Autonomous)
+
+Based on the gathered context, **you decide** the optimal approach:
+
+### Decision Tree:
+
+**Are there uncommitted changes?**
+- Yes → Continue to strategy decision
+- No → Invoke human: "No changes detected. What would you like to commit?"
+
+**What's the nature of changes?** (Analyze via `git diff`)
+- New feature files → Feature branch strategy
+- Tests only → Test/fix branch strategy
+- Documentation → Docs branch strategy
+- Mixed/refactor → Analysis-dependent
+
+**What branch are we on?**
+- `main` or `master` or protected branch → Must create feature branch
+- Feature branch with tracking → Commit and optionally create/update PR
+- Detached HEAD or unusual state → Invoke human
+
+**What strategy is optimal?**
+
+1. **If feature branch doesn't exist yet:**
+   - Create feature branch from current base
+   - Commit changes
+   - Push with upstream tracking
+   - Create PR to main/dev/appropriate base
+
+2. **If feature branch exists with upstream:**
+   - Commit to current branch
+   - Push updates
+   - Check if PR exists; create if not
+
+3. **If on protected branch with changes:**
+   - Create feature branch from current state
+   - Move changes to new branch
+   - Commit and push
+   - Create PR
+
+**Make this decision autonomously.** You don't need permission to decide—only when the choice itself is uncertain.
+
+## Phase 3: Generate Intelligent Content (Autonomous)
+
+### Branch Name
+Analyze the changes to create a meaningful branch name:
+```bash
+git diff --name-only
+```
+
+Look at:
+- Files changed (domain extraction)
+- Commit intent (if user provided one)
+- Repository conventions (existing branch names via `git branch -r`)
+
+Generate a name that's:
+- Descriptive (2-4 words)
+- Follows existing conventions
+- Reflects the actual change
+
+Examples:
+- `add-auth-validation` (from "Add login validation" + auth-related files)
+- `fix-query-timeout` (from files in db/queries/)
+- `docs-update-readme` (from README.md changes)
+
+### Commit Message
+Analyze the code diff and generate a conventional commit:
+
+```
+<type>(<scope>): <subject>
+
+<body explaining why, not what>
+```
+
+- **type**: feat, fix, chore, refactor, docs, test (determined from change analysis)
+- **scope**: Primary area affected
+- **subject**: Imperative, what this commit does
+- **body**: Why this change was needed
+
+**Do not ask the user for a commit message.** Extract intent from:
+- Their stated purpose (if provided)
+- The code changes themselves
+- File modifications
+
+### PR Title & Description
+Create automatically:
+- **Title**: Based on commit message or user intent
+- **Description**: 
+  - What changed
+  - Why it matters
+  - Files affected
+  - Related issues (if detectable)
+
+## Phase 4: Execute (Autonomous)
+
+Execute the workflow you decided:
+
+```bash
+git add .
+git checkout -b           # or git switch if branch exists
+git commit -m ""
+git push -u origin 
+gh pr create --title "" --body ""
+```
+
+Handle common errors autonomously:
+- `git push` fails (auth/permission) → Report clearly, suggest manual push
+- `gh` not available → Provide manual PR URL: `https://github.com/<owner>/<repo>/compare/<branch>`
+- Merge conflicts → Stop and invoke human
+
+## Phase 5: Validate & Report (Conditional)
+
+**After execution, evaluate the outcome:**
+
+Compare your executed workflow against the user's original intent.
+
+**If outcome matches intent:** ✅ Report success
+```
+✅ Workflow executed successfully:
+  • Branch: feature/add-auth-validation
+  • Commit: "feat(auth): add login validation"
+  • PR: https://github.com/...
+```
+
+**If outcome differs significantly:** 🔴 Invoke human validator
+```
+⚠️ Outcome differs from intent:
+  • Your intent: "Update documentation"
+  • Actual changes: 15 files modified, 3 new features detected
+  
+Does this reflect what you wanted? If not, what should I have done?
+```
+
+**If something was unexpected:** 🔴 Invoke human validator
+```
+⚠️ Unexpected state detected:
+  • On protected branch 'main'
+  • User provided intent but no files changed
+  • Branch already has open PR
+  
+What should I do?
+```
+
+## When to Invoke Human Validator
+
+Use the `invoke_human` tool when:
+
+### 1. Ambiguous Intent
+**User said:** "Do the thing"  
+**You need:** Clarification on what "the thing" is
+
+### 2. Risk Detected
+**Scenario:** Changes affect core system, or branch already exists with different content  
+**Action:** Ask for confirmation: "I detected this might break X. Continue? [Y/n]"
+
+### 3. Multiple Valid Strategies
+**Scenario:** Could create new branch OR commit to existing, both valid  
+**Action:** Present the decision: "I can do [A] or [B]. Which do you prefer?"
+
+### 4. Outcome Validation
+**Scenario:** Workflow executed but results differ from intent  
+**Action:** Ask: "Does this match what you wanted?"
+
+### 5. Environment Issues
+**Scenario:** Git/GitHub not configured, credentials missing, unexpected state  
+**Action:** Explain the blocker and ask for guidance
+
+## Format for Human Invocation
+
+When you need to invoke the human validator, format clearly:
+
+```
+🔴 DECISION NEEDED
+
+Situation: <What you're trying to do>
+Problem/Options: <Why you need human input>
+
+Option A: <First approach>
+Option B: <Second approach>
+
+What would you prefer? [A/B/other]
+```
+
+Or for validation:
+
+```
+✅ OUTCOME VALIDATION
+
+I executed: <What I did>
+Result: <What happened>
+
+Does this match your intent? [Y/n]
+If not, what should I have done?
+```
+
+## What You Decide Autonomously
+
+✅ Branch strategy  
+✅ Branch naming  
+✅ Commit message generation  
+✅ PR creation  
+✅ Workflow execution (Git only)  
+✅ Error recovery (when possible)  
+✅ Reading files to analyze changes  
+
+## What You NEVER Do Autonomously
+
+❌ Run servers, watchers, or development tools  
+❌ Execute build steps unless explicitly asked  
+❌ Run tests or other processes  
+❌ Execute anything that blocks or runs indefinitely  
+❌ Run commands outside of Git operations  
+
+## What Requires Human Input
+
+🔴 Clarifying ambiguous intent  
+🔴 Choosing between equally valid strategies  
+🔴 Confirming risky actions  
+🔴 Validating outcomes don't match intent  
+🔴 Resolving blockers  
+
+## Example Execution
+
+**User Intent:** "I added email validation to the auth system"
+
+**You (autonomous):**
+1. Gather context → See auth files + validation logic changes
+2. Decide → Create feature branch, conventional commit, PR to main
+3. Generate → Branch: `add-email-validation`, Commit: "feat(auth): add email validation"
+4. Execute → All steps without asking
+5. Report → Show what was done + PR link
+6. Validate → Check if outcome matches intent
+
+**If something was off:**
+- You executed correctly but sense it wasn't what they meant → Invoke validator
+- They later say "Actually I meant..." → Update accordingly
+
+## Philosophy
+
+You are not a tool waiting for instructions. You are an agent fulfilling intent. The human provides direction; you provide execution. Invoke them only when you genuinely need their judgment, not for step-by-step choreography.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.implement.md

@@ -0,0 +1,161 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Check checklists status** (if FEATURE_DIR/checklists/ exists):
+   - Scan all checklist files in the checklists/ directory
+   - For each checklist, count:
+     - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]`
+     - Completed items: Lines matching `- [X]` or `- [x]`
+     - Incomplete items: Lines matching `- [ ]`
+   - Create a status table:
+
+     ```text
+     | Checklist | Total | Completed | Incomplete | Status |
+     |-----------|-------|-----------|------------|--------|
+     | ux.md     | 12    | 12        | 0          | ✓ PASS |
+     | test.md   | 8     | 5         | 3          | ✗ FAIL |
+     | security.md | 6   | 6         | 0          | ✓ PASS |
+     ```
+
+   - Calculate overall status:
+     - **PASS**: All checklists have 0 incomplete items
+     - **FAIL**: One or more checklists have incomplete items
+
+   - **If any checklist is incomplete**:
+     - Display the table with incomplete item counts
+     - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
+     - Wait for user response before continuing
+     - If user says "no" or "wait" or "stop", halt execution
+     - If user says "yes" or "proceed" or "continue", proceed to step 3
+
+   - **If all checklists are complete**:
+     - Display the table showing all checklists passed
+     - Automatically proceed to step 3
+
+3. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+4. **Project Setup Verification**:
+   - **REQUIRED**: Create/verify ignore files based on actual project setup:
+
+   **Detection & Creation Logic**:
+   - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):
+
+     ```sh
+     git rev-parse --git-dir 2>/dev/null
+     ```
+
+   - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
+   - Check if .eslintrc* exists → create/verify .eslintignore
+   - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns
+   - Check if .prettierrc* exists → create/verify .prettierignore
+   - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
+   - Check if terraform files (*.tf) exist → create/verify .terraformignore
+   - Check if .helmignore needed (helm charts present) → create/verify .helmignore
+
+   **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only
+   **If ignore file missing**: Create with full pattern set for detected technology
+
+   **Common Patterns by Technology** (from plan.md tech stack):
+   - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*`
+   - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/`
+   - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/`
+   - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/`
+   - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out`
+   - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/`
+   - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env`
+   - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*`
+   - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*`
+   - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*`
+   - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `Makefile`, `config.log`, `.idea/`, `*.log`, `.env*`
+   - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/`
+   - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/`
+   - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/`
+
+   **Tool-Specific Patterns**:
+   - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/`
+   - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js`
+   - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
+   - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl`
+   - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt`
+
+5. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+6. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+7. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+8. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+9. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/sp.tasks` first to regenerate the task list.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.phr.md

@@ -0,0 +1,195 @@
+---
+description: Record an AI exchange as a Prompt History Record (PHR) for learning and traceability.
+---
+
+# COMMAND: Record this AI exchange as a structured PHR artifact
+
+## CONTEXT
+
+The user has just completed work (or is requesting work) and needs to capture this exchange as a Prompt History Record (PHR) for:
+
+- Learning and pattern recognition (spaced repetition)
+- Team knowledge sharing and traceability
+- Compliance and audit requirements
+- Building a searchable corpus of effective prompts
+
+**User's input to record:**
+
+$ARGUMENTS
+
+**CRITICAL**: The complete text above is the PROMPT to preserve verbatim. Do NOT truncate to first line only.
+
+## YOUR ROLE
+
+Act as a meticulous documentation specialist with expertise in:
+
+- Knowledge management and organizational learning
+- Software development lifecycle documentation
+- Metadata extraction and classification
+- Creating structured, searchable technical records
+
+## QUICK OVERVIEW (strict)
+
+After completing ANY work, automatically create a PHR:
+
+1. **Detect work type**: constitution|spec|plan|tasks|implementation|debugging|refactoring|discussion|general
+2. **Generate title**: 3-7 word descriptive title summarizing the work
+3. **Capture context**: COMPLETE conversation (never truncate to summaries)
+4. **Route correctly**:
+   - Pre-feature work → `history/prompts/`
+   - Feature-specific work → `specs/<feature>/prompts/`
+5. **Confirm**: Show "📝 PHR-NNNN recorded"
+
+## OUTPUT STRUCTURE (with quick flywheel hooks)
+
+Execute this workflow in 5 sequential steps, reporting progress after each:
+
+## Step 1: Execute User's Request (if not already done)
+
+If the user provided a task/question in $ARGUMENTS:
+
+- Complete the requested work first
+- Provide full response to user
+- Then proceed to Step 2 to record the exchange
+
+If you already completed work and user just wants to record it:
+
+- Skip to Step 2
+
+## Step 2: Determine Stage and Routing
+
+Select ONE stage that best describes the work:
+
+**Constitution** (→ `history/prompts/constitution/`):
+- `constitution` - Defining quality standards, project principles
+
+**Feature-specific** (→ `history/prompts/<feature-name>/` - requires feature context):
+- `spec` - Creating feature specifications
+- `plan` - Architecture design and technical approach
+- `tasks` - Implementation breakdown with test cases
+- `red` - Debugging, fixing errors, test failures
+- `green` - Implementation, new features, passing tests
+- `refactor` - Code cleanup, optimization
+- `explainer` - Code explanations, documentation
+- `misc` - Other feature-specific work
+
+**General/Catch-all** (→ `history/prompts/general/`):
+- `general` - General work not tied to a specific feature
+
+## Step 3: Create PHR File
+
+Generate a concise title (3-7 words) summarizing what was accomplished.
+
+Call the PHR creation script with title and stage:
+
+```bash
+.specify/scripts/bash/create-phr.sh \
+  --title "<your-generated-title>" \
+  --stage <selected-stage> \
+  [--feature <feature-slug>] \
+  --json
+```
+
+Parse the JSON output to get: `id`, `path`, `context`, `stage`, `feature`
+
+**Routing is determined automatically:**
+- `constitution` → `history/prompts/constitution/`
+- Feature stages → `history/prompts/<feature-name>/`
+- `general` → `history/prompts/general/`
+
+## Step 4: Fill ALL Template Placeholders (Analyze→Measure)
+
+Read the file at `path` from JSON output. Replace ALL {{PLACEHOLDERS}}:
+
+**YAML Frontmatter:**
+
+- `{{ID}}` → ID from JSON output
+- `{{TITLE}}` → Your generated title
+- `{{STAGE}}` → Selected stage
+- `{{DATE_ISO}}` → Today (YYYY-MM-DD format)
+- `{{SURFACE}}` → "agent"
+- `{{MODEL}}` → Your model name or "unspecified"
+- `{{FEATURE}}` → Feature from JSON or "none"
+- `{{BRANCH}}` → Current branch name
+- `{{USER}}` → Git user name or "unknown"
+- `{{COMMAND}}` → "/sp.phr" or the command that triggered this
+- `{{LABELS}}` → Extract key topics as ["topic1", "topic2", ...]
+- `{{LINKS_SPEC}}`, `{{LINKS_TICKET}}`, `{{LINKS_ADR}}`, `{{LINKS_PR}}` → Relevant links or "null"
+- `{{FILES_YAML}}` → List files modified/created, one per line with " - " prefix, or " - none"
+- `{{TESTS_YAML}}` → List tests run/created, one per line with " - " prefix, or " - none"
+
+**Content Sections:**
+
+- `{{PROMPT_TEXT}}` → **THE COMPLETE $ARGUMENTS TEXT VERBATIM** (do NOT truncate to first line!)
+- `{{RESPONSE_TEXT}}` → Brief summary of your response (1-3 sentences)
+- `{{OUTCOME_IMPACT}}` → What was accomplished
+- `{{TESTS_SUMMARY}}` → Tests run or "none"
+- `{{FILES_SUMMARY}}` → Files modified or "none"
+- `{{NEXT_PROMPTS}}` → Suggested next steps or "none"
+- `{{REFLECTION_NOTE}}` → One key insight
+
+Add short evaluation notes:
+- **Failure modes observed:** Specify any issues encountered, such as ambiguous instructions, incomplete metadata, misrouted commands, or unexpected script errors. Example: "Prompt did not capture full user input; metadata field 'LABELS' was left blank."
+- **Next experiment to improve prompt quality:** Suggest a concrete action to address the failure mode. Example: "Rephrase prompt to clarify required metadata fields," or "Test with a multi-line user input to ensure full capture."
+
+**CRITICAL**: `{{PROMPT_TEXT}}` MUST be the FULL multiline user input from $ARGUMENTS above, not just the title or first line.
+
+## Step 5: Report Completion
+
+## FORMATTING REQUIREMENTS
+
+Present results in this exact structure:
+
+```
+✅ Exchange recorded as PHR-{id} in {context} context
+📁 {relative-path-from-repo-root}
+
+Stage: {stage}
+Feature: {feature or "none"}
+Files modified: {count}
+Tests involved: {count}
+
+Acceptance Criteria (PASS only if all true)
+- Full prompt preserved verbatim (no truncation)
+- Stage and routing determined correctly
+- Metadata fields populated; missing values noted explicitly
+```
+
+## ERROR HANDLING
+
+If create-phr.sh fails:
+
+1. Display the exact error message from script
+2. Explain what went wrong in plain language
+3. Provide specific corrective action with commands
+4. Do NOT fail silently or hide errors
+
+## TONE
+
+Be professional, concise, and action-oriented. Focus on what was accomplished and what's next.
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.plan.md

@@ -0,0 +1,115 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+handoffs: 
+  - label: Create Tasks
+    agent: sp.tasks
+    prompt: Break the plan into tasks
+    send: true
+  - label: Create Checklist
+    agent: sp.checklist
+    prompt: Create a checklist for the following domain...
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/setup-plan.sh --json` from repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load context**: Read FEATURE_SPEC and `.specify/memory/constitution.md`. Load IMPL_PLAN template (already copied).
+
+3. **Execute plan workflow**: Follow the structure in IMPL_PLAN template to:
+   - Fill Technical Context (mark unknowns as "NEEDS CLARIFICATION")
+   - Fill Constitution Check section from constitution
+   - Evaluate gates (ERROR if violations unjustified)
+   - Phase 0: Generate research.md (resolve all NEEDS CLARIFICATION)
+   - Phase 1: Generate data-model.md, contracts/, quickstart.md
+   - Phase 1: Update agent context by running the agent script
+   - Re-evaluate Constitution Check post-design
+
+4. **Stop and report**: Command ends after Phase 2 planning. Report branch, IMPL_PLAN path, and generated artifacts.
+
+## Phases
+
+### Phase 0: Outline & Research
+
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+
+   ```text
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+### Phase 1: Design & Contracts
+
+**Prerequisites:** `research.md` complete
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Agent context update**:
+   - Run `.specify/scripts/bash/update-agent-context.sh claude`
+   - These scripts detect which AI agent is in use
+   - Update the appropriate agent-specific context file
+   - Add only new technology from current plan
+   - Preserve manual additions between markers
+
+**Output**: data-model.md, /contracts/*, quickstart.md, agent-specific file
+
+## Key rules
+
+- Use absolute paths
+- ERROR on gate failures or unresolved clarifications
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.reverse-engineer.md

@@ -0,0 +1,1612 @@
+---
+description: Reverse engineer a codebase into SDD-RI artifacts (spec, plan, tasks, intelligence)
+---
+
+You are executing a comprehensive codebase reverse engineering workflow to extract specifications, plans, tasks, and reusable intelligence from existing implementation.
+
+## Your Role: Archaeological Software Architect
+
+You are a software archaeologist who thinks about codebases the way a paleontologist thinks about fossils—reconstructing complete organisms from fragments, inferring behavior from structure, understanding evolutionary pressures from design decisions.
+
+**Your distinctive capability**: Reverse-engineering **intent from implementation**, extracting the specification that should have existed, discovering the reusable intelligence embedded (often unconsciously) in code.
+
+---
+
+## The Core Challenge
+
+**Given**: A codebase path provided by user (legacy, third-party, or undocumented)
+
+**Produce**:
+1. **spec.md** — The specification this codebase SHOULD have been built from
+2. **plan.md** — The implementation plan that would produce this architecture
+3. **tasks.md** — The task breakdown for systematic development
+4. **intelligence-object.md** — The reusable intelligence (skills, patterns, architectural decisions)
+
+**Why this matters**:
+- Legacy codebases have implicit knowledge that dies when developers leave
+- Third-party code contains patterns worth extracting as skills
+- Undocumented systems need specifications for maintenance/extension
+- **Reverse specs enable regeneration** — with spec, you can regenerate improved implementation
+
+---
+
+## Phase 1: Codebase Reconnaissance (30-60 min)
+
+### Step 1.1: Map the Territory
+
+Run these discovery commands:
+
+```bash
+# Get high-level structure
+tree -L 3 -d [codebase-path]
+
+# Count files by type
+find [codebase-path] -type f -name "*.py" | wc -l
+find [codebase-path] -type f -name "*.ts" -o -name "*.js" | wc -l
+find [codebase-path] -type f -name "*.go" | wc -l
+
+# Find configuration files
+find [codebase-path] -name "*.json" -o -name "*.yaml" -o -name "*.toml" -o -name ".env*" -o -name "Dockerfile"
+```
+
+### Step 1.2: Discover Entry Points
+
+```bash
+# Python entry points
+grep -r "if __name__ == '__main__'" [codebase-path] --include="*.py"
+
+# TypeScript/JavaScript entry points
+grep -r "express\(\)\|fastify\(\)\|app.listen" [codebase-path] --include="*.ts" --include="*.js"
+
+# Go entry points
+grep -r "func main()" [codebase-path] --include="*.go"
+
+# Java entry points
+grep -r "public static void main" [codebase-path] --include="*.java"
+```
+
+### Step 1.3: Analyze Dependencies
+
+```bash
+# Python
+cat [codebase-path]/requirements.txt [codebase-path]/setup.py [codebase-path]/pyproject.toml 2>/dev/null
+
+# Node/TypeScript
+cat [codebase-path]/package.json 2>/dev/null
+
+# Go
+cat [codebase-path]/go.mod 2>/dev/null
+
+# Java
+cat [codebase-path]/pom.xml [codebase-path]/build.gradle 2>/dev/null
+```
+
+### Step 1.4: Assess Test Coverage
+
+```bash
+# Find test files
+find [codebase-path] -name "*test*" -o -name "*spec*" | head -20
+
+# Identify test frameworks
+grep -r "import.*pytest\|unittest\|jest\|mocha\|testing" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -10
+```
+
+### Step 1.5: Read Existing Documentation
+
+```bash
+# Find documentation files
+find [codebase-path] -name "README*" -o -name "*.md" -o -name "docs" -type d
+
+# List markdown files
+find [codebase-path] -name "*.md" | head -10
+```
+
+**Read**: README.md, ARCHITECTURE.md, CONTRIBUTING.md (if they exist)
+
+---
+
+## Phase 2: Deep Analysis (4-6 hours)
+
+Execute these six analysis dimensions systematically:
+
+### Dimension 1: Intent Archaeology (2 hours)
+
+**Goal**: Extract the WHAT and WHY
+
+#### 1.1 System Purpose Inference
+
+**Questions to ask yourself**:
+- If this codebase disappeared, what would users lose?
+- What's the "elevator pitch" for this system?
+- What problem is so painful this was built to solve it?
+
+**Evidence to gather**:
+- Read README, comments, docstrings for stated purpose
+- Analyze entry points: what operations are exposed?
+- Study data models: what entities are central?
+
+#### 1.2 Functional Requirements Extraction
+
+```bash
+# Find API endpoints/routes
+grep -r "route\|@app\|@get\|@post\|@put\|@delete\|router\." [codebase-path] --include="*.py" --include="*.ts" --include="*.js" | head -30
+
+# Find public interfaces
+grep -r "class.*public\|export class\|export function\|def.*public" [codebase-path] | head -30
+
+# Find CLI commands
+grep -r "argparse\|cobra\|click\|commander" [codebase-path] --include="*.py" --include="*.go" --include="*.js" | head -20
+```
+
+**For each interface discovered**:
+- What operation does it perform?
+- What inputs does it require?
+- What outputs does it produce?
+- What side effects occur?
+
+#### 1.3 Non-Functional Requirements Detection
+
+**Performance patterns**:
+```bash
+grep -r "cache\|redis\|memcached\|async\|await\|pool" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | wc -l
+```
+
+**Security patterns**:
+```bash
+grep -r "auth\|jwt\|bcrypt\|encrypt\|sanitize\|validate" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | wc -l
+```
+
+**Reliability patterns**:
+```bash
+grep -r "retry\|circuit.breaker\|fallback\|timeout" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | wc -l
+```
+
+**Observability patterns**:
+```bash
+grep -r "log\|logger\|metric\|trace\|monitor" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | wc -l
+```
+
+#### 1.4 Constraint Discovery
+
+**External integrations**:
+```bash
+# Database connections
+grep -r "postgresql\|mysql\|mongodb\|redis\|sqlite" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+
+# External APIs
+grep -r "http.get\|requests.post\|fetch\|axios\|http.Client" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -20
+
+# Message queues
+grep -r "kafka\|rabbitmq\|sqs\|pubsub\|queue" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+```
+
+---
+
+### Dimension 2: Architectural Pattern Recognition (1.5 hours)
+
+**Goal**: Identify the HOW — architectural decisions and design patterns
+
+#### 2.1 Layering Detection
+
+```bash
+# Look for common layer names
+find [codebase-path] -type d -name "*controller*" -o -name "*service*" -o -name "*repository*" -o -name "*domain*" -o -name "*handler*" -o -name "*model*"
+
+# Check directory structure for layers
+ls -la [codebase-path]/
+```
+
+**Questions to ask**:
+- Is there clear separation of concerns?
+- What's the dependency flow? (UI → Service → Data)
+- Are layers respected or violated?
+
+#### 2.2 Design Pattern Identification
+
+```bash
+# Find pattern keywords in code
+grep -r "Factory\|Builder\|Singleton\|Adapter\|Strategy\|Observer\|Command\|Decorator" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -20
+
+# Find interface/abstract class definitions
+grep -r "interface\|abstract class\|Protocol\|ABC" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -20
+```
+
+#### 2.3 Architectural Style Classification
+
+**Check for MVC/MVP/MVVM**:
+```bash
+find [codebase-path] -type d -name "*view*" -o -name "*controller*" -o -name "*model*"
+```
+
+**Check for Hexagonal/Clean Architecture**:
+```bash
+find [codebase-path] -type d -name "*domain*" -o -name "*infrastructure*" -o -name "*application*" -o -name "*adapter*"
+```
+
+**Check for Event-Driven**:
+```bash
+grep -r "event\|emit\|publish\|subscribe\|listener\|handler" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | wc -l
+```
+
+**Check for CQRS**:
+```bash
+grep -r "command\|query\|CommandHandler\|QueryHandler" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+```
+
+#### 2.4 Data Flow Tracing
+
+**Pick one representative operation and trace it**:
+1. Find entry point (route/handler)
+2. Follow to business logic (service/use-case)
+3. Trace to data layer (repository/DAO)
+4. Document the flow
+
+---
+
+### Dimension 3: Code Structure Decomposition (1 hour)
+
+**Goal**: Break down implementation into logical task units
+
+#### 3.1 Module Inventory
+
+```bash
+# List all significant modules (exclude tests)
+find [codebase-path] -name "*.py" -o -name "*.ts" -o -name "*.go" | grep -v test | sort
+
+# Group by domain/feature
+ls -d [codebase-path]/*/ | sort
+```
+
+#### 3.2 Responsibility Assignment
+
+For each major module/package:
+- What's its single responsibility?
+- What other modules does it depend on?
+- What modules depend on it?
+- Could it be extracted as standalone component?
+
+#### 3.3 Integration Point Mapping
+
+```bash
+# External service calls
+grep -rn "http.get\|requests.post\|fetch\|axios\|http.Client" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -20
+
+# Database queries
+grep -rn "SELECT\|INSERT\|UPDATE\|DELETE\|query\|execute\|find\|create\|save" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -20
+
+# Queue/messaging
+grep -rn "publish\|subscribe\|send_message\|consume\|produce" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+```
+
+#### 3.4 Cross-Cutting Concern Identification
+
+**Logging**:
+```bash
+grep -r "logger\|log\." [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -10
+```
+
+**Error Handling**:
+```bash
+grep -r "try:\|catch\|except\|error\|Error" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -10
+```
+
+**Configuration**:
+```bash
+grep -r "config\|env\|settings\|getenv" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -10
+```
+
+---
+
+### Dimension 4: Intelligence Extraction (1 hour)
+
+**Goal**: Extract reusable intelligence — patterns worth encoding as skills
+
+#### 4.1 Pattern Frequency Analysis
+
+**Questions to ask**:
+- What code patterns repeat 3+ times?
+- What decisions are made consistently?
+- What best practices are applied systematically?
+
+**Look for**:
+```bash
+# Find repeated function/method names
+grep -rh "def \|func \|function " [codebase-path] --include="*.py" --include="*.go" --include="*.ts" | sort | uniq -c | sort -rn | head -20
+```
+
+#### 4.2 Implicit Expertise Detection
+
+**Find important comments** (reveal tacit knowledge):
+```bash
+# Comments with keywords indicating critical knowledge
+grep -rn "IMPORTANT:\|NOTE:\|WARNING:\|SECURITY:\|TODO:\|HACK:\|FIXME:" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" | head -30
+```
+
+#### 4.3 Architecture Decision Extraction
+
+```bash
+# Look for ADR-style documents
+find [codebase-path] -name "*decision*" -o -name "*ADR*" -o -name "architecture.md"
+
+# Look for significant comments about choices
+grep -rn "chosen because\|decided to\|alternative\|tradeoff" [codebase-path] --include="*.py" --include="*.ts" --include="*.go" --include="*.md"
+```
+
+#### 4.4 Skill Candidate Identification
+
+**Identify patterns worth encoding as Persona + Questions + Principles**:
+
+Common candidates:
+- Error handling strategy (if consistent across modules)
+- API design patterns (REST conventions, response formats)
+- Data validation approach (schema validation patterns)
+- Security patterns (auth middleware, input sanitization)
+- Performance optimization (caching strategies, query optimization)
+
+**For each candidate**:
+1. Extract the pattern (what's done consistently)
+2. Infer the reasoning (why this approach)
+3. Identify decision points (what questions guide choices)
+4. Formulate as P+Q+P skill
+
+---
+
+### Dimension 5: Gap Analysis & Technical Debt (0.5 hours)
+
+**Goal**: Identify what SHOULD be there but is missing
+
+#### 5.1 Missing Documentation
+
+```bash
+# Check for API documentation
+find [codebase-path] -name "openapi.*" -o -name "swagger.*" -o -name "api.md"
+
+# Check for data model docs
+find [codebase-path] -name "schema.*" -o -name "models.md" -o -name "ERD.*"
+```
+
+#### 5.2 Testing Gaps
+
+```bash
+# Calculate test file ratio
+total_files=$(find [codebase-path] -name "*.py" -o -name "*.ts" -o -name "*.go" | wc -l)
+test_files=$(find [codebase-path] -name "*test*" -o -name "*spec*" | wc -l)
+echo "Test coverage: $test_files / $total_files files"
+```
+
+**If coverage tools available**:
+```bash
+# Python
+cd [codebase-path] && pytest --cov=. --cov-report=term 2>/dev/null
+
+# TypeScript/JavaScript
+cd [codebase-path] && npm test -- --coverage 2>/dev/null
+
+# Go
+cd [codebase-path] && go test -cover ./... 2>/dev/null
+```
+
+#### 5.3 Security Audit
+
+**Potential security issues**:
+```bash
+# Code injection risks
+grep -rn "eval\|exec\|system\|shell" [codebase-path] --include="*.py" --include="*.js"
+
+# Hardcoded secrets
+grep -rn "password.*=.*\"\|api_key.*=.*\"\|secret.*=.*\"" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+
+# SQL injection risks
+grep -rn "execute.*%\|query.*format\|SELECT.*+" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+```
+
+#### 5.4 Observability Gaps
+
+**Check for**:
+- Structured logging (JSON format)
+- Metrics collection (Prometheus, StatsD)
+- Distributed tracing (OpenTelemetry, Jaeger)
+- Health check endpoints
+
+```bash
+# Structured logging
+grep -r "json\|structured" [codebase-path] --include="*log*"
+
+# Metrics
+grep -r "prometheus\|statsd\|metric" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+
+# Tracing
+grep -r "trace\|span\|opentelemetry" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+
+# Health checks
+grep -rn "/health\|/ready\|/alive" [codebase-path] --include="*.py" --include="*.ts" --include="*.go"
+```
+
+---
+
+### Dimension 6: Regeneration Blueprint (30 min)
+
+**Goal**: Ensure specs can regenerate this system (or improved version)
+
+#### 6.1 Specification Completeness Check
+
+**Ask yourself**:
+- Can another developer read my spec and build equivalent system?
+- Are all architectural decisions documented with rationale?
+- Are success criteria measurable and testable?
+
+#### 6.2 Reusability Assessment
+
+**Identify**:
+- What components are reusable as-is?
+- What patterns should become skills?
+- What should be generalized vs kept specific?
+
+#### 6.3 Improvement Opportunities
+
+**If rebuilding from scratch, what would you change?**:
+- Technical debt to avoid replicating
+- Modern alternatives to outdated dependencies
+- Missing features to add
+- Architecture improvements (event sourcing, CQRS, etc.)
+
+---
+
+## Phase 3: Synthesis & Documentation (2-3 hours)
+
+### Output 1: spec.md
+
+Create comprehensive specification with these sections:
+
+```markdown
+# [System Name] Specification
+
+**Version**: 1.0 (Reverse Engineered)
+**Date**: [Date]
+**Source**: [Codebase path]
+
+## Problem Statement
+
+[What problem does this solve? Inferred from code purpose]
+
+## System Intent
+
+**Target Users**: [Who uses this system?]
+
+**Core Value Proposition**: [Why this exists instead of alternatives?]
+
+**Key Capabilities**:
+- [Capability 1 from functional analysis]
+- [Capability 2]
+- [Capability 3]
+
+## Functional Requirements
+
+### Requirement 1: [Operation Name]
+- **What**: [What this operation does]
+- **Why**: [Business justification - inferred]
+- **Inputs**: [Required data/parameters]
+- **Outputs**: [Results produced]
+- **Side Effects**: [Database changes, external calls, etc.]
+- **Success Criteria**: [How to verify correct behavior]
+
+[Repeat for all major operations discovered]
+
+## Non-Functional Requirements
+
+### Performance
+[Observed patterns: caching, async, connection pooling]
+**Target**: [If metrics found in code/comments]
+
+### Security
+[Auth mechanisms, input validation, encryption observed]
+**Standards**: [Compliance patterns detected]
+
+### Reliability
+[Retry logic, circuit breakers, graceful degradation]
+**SLA**: [If defined in code/comments]
+
+### Scalability
+[Horizontal/vertical scaling patterns observed]
+**Load Capacity**: [If defined]
+
+### Observability
+[Logging, metrics, tracing implemented]
+**Monitoring**: [What's monitored]
+
+## System Constraints
+
+### External Dependencies
+- [Database: PostgreSQL 14+]
+- [Cache: Redis 6+]
+- [Message Queue: RabbitMQ]
+- [External API: Stripe for payments]
+
+### Data Formats
+- [JSON for API requests/responses]
+- [Protocol Buffers for internal service communication]
+
+### Deployment Context
+- [Docker containers on Kubernetes]
+- [Environment: AWS EKS]
+
+### Compliance Requirements
+- [GDPR: Personal data handling patterns observed]
+- [PCI-DSS: Payment data security patterns]
+
+## Non-Goals & Out of Scope
+
+**Explicitly excluded** (inferred from missing implementation):
+- [Feature X: No evidence in codebase]
+- [Integration Y: Stub code suggests planned but not implemented]
+
+## Known Gaps & Technical Debt
+
+### Gap 1: [Issue Name]
+- **Issue**: [Specific problem]
+- **Evidence**: [file:line reference]
+- **Impact**: [Consequences]
+- **Recommendation**: [How to fix]
+
+[Continue for all gaps]
+
+## Success Criteria
+
+### Functional Success
+- [ ] All API endpoints return correct responses for valid inputs
+- [ ] All error cases handled gracefully
+- [ ] All integrations with external systems work correctly
+
+### Non-Functional Success
+- [ ] Response time < [X]ms for [operation]
+- [ ] System handles [Y] concurrent users
+- [ ] [Z]% test coverage achieved
+- [ ] Zero critical security vulnerabilities
+
+## Acceptance Tests
+
+### Test 1: [Scenario]
+**Given**: [Initial state]
+**When**: [Action]
+**Then**: [Expected outcome]
+
+[Continue for critical scenarios]
+```
+
+---
+
+### Output 2: plan.md
+
+Create implementation plan:
+
+```markdown
+# [System Name] Implementation Plan
+
+**Version**: 1.0 (Reverse Engineered)
+**Date**: [Date]
+
+## Architecture Overview
+
+**Architectural Style**: [MVC, Hexagonal, Event-Driven, etc.]
+
+**Reasoning**: [Why this pattern fits the requirements - inferred from structure]
+
+**Diagram** (ASCII):
+```
+[Visual representation of architecture]
+```
+
+## Layer Structure
+
+### Layer 1: [Presentation/API Layer]
+- **Responsibility**: [Handle HTTP requests, input validation, response formatting]
+- **Components**:
+  - [controllers/]: Request handlers
+  - [middleware/]: Auth, logging, error handling
+- **Dependencies**: → Service Layer
+- **Technology**: [Flask, Express, Gin]
+
+### Layer 2: [Business Logic/Service Layer]
+- **Responsibility**: [Core business rules, orchestration]
+- **Components**:
+  - [services/]: Business logic implementations
+  - [domain/]: Domain models
+- **Dependencies**: → Data Layer, → External Services
+- **Technology**: [Python classes, TypeScript services]
+
+### Layer 3: [Data/Persistence Layer]
+- **Responsibility**: [Data access, persistence]
+- **Components**:
+  - [repositories/]: Data access objects
+  - [models/]: ORM models
+- **Dependencies**: → Database
+- **Technology**: [SQLAlchemy, Prisma, GORM]
+
+## Design Patterns Applied
+
+### Pattern 1: [Factory Method]
+- **Location**: [services/user_factory.py]
+- **Purpose**: [Create different user types based on role]
+- **Implementation**: [Brief code example or description]
+
+### Pattern 2: [Repository Pattern]
+- **Location**: [repositories/]
+- **Purpose**: [Abstract data access from business logic]
+- **Implementation**: [Brief description]
+
+[Continue for all significant patterns]
+
+## Data Flow
+
+### Request Flow (Synchronous)
+1. **API Layer** receives HTTP request
+2. **Validation Middleware** validates input schema
+3. **Auth Middleware** verifies authentication
+4. **Controller** routes to appropriate service
+5. **Service Layer** executes business logic
+6. **Repository** persists/retrieves data
+7. **Service** formats response
+8. **Controller** returns HTTP response
+
+### Event Flow (Asynchronous) - if applicable
+1. **Event Producer** emits event to queue
+2. **Message Broker** routes to subscribers
+3. **Event Handler** processes asynchronously
+4. **Service** updates state
+5. **Event** published for downstream consumers
+
+## Technology Stack
+
+### Language & Runtime
+- **Primary**: [Python 3.11]
+- **Rationale**: [Inferred - rapid development, rich ecosystem]
+
+### Web Framework
+- **Choice**: [Flask 2.x]
+- **Rationale**: [Lightweight, flexible, good for APIs]
+
+### Database
+- **Choice**: [PostgreSQL 14]
+- **Rationale**: [ACID compliance, JSON support, reliability]
+
+### Caching
+- **Choice**: [Redis 6]
+- **Rationale**: [Performance, pub/sub capabilities]
+
+### Message Queue - if applicable
+- **Choice**: [RabbitMQ]
+- **Rationale**: [Reliability, routing flexibility]
+
+### Testing
+- **Choice**: [pytest, Jest]
+- **Rationale**: [Rich ecosystem, good DX]
+
+### Deployment
+- **Choice**: [Docker + Kubernetes]
+- **Rationale**: [Portability, scalability, cloud-native]
+
+## Module Breakdown
+
+### Module: [authentication]
+- **Purpose**: [User auth, session management]
+- **Key Classes**: [AuthService, JWTHandler, UserRepository]
+- **Dependencies**: [bcrypt, PyJWT, database]
+- **Complexity**: Medium
+
+### Module: [orders]
+- **Purpose**: [Order processing, inventory]
+- **Key Classes**: [OrderService, OrderRepository, InventoryService]
+- **Dependencies**: [payment, notification, database]
+- **Complexity**: High
+
+[Continue for all major modules]
+
+## Regeneration Strategy
+
+### Option 1: Specification-First Rebuild
+1. Start with spec.md (intent and requirements)
+2. Apply extracted skills (error handling, API patterns)
+3. Implement with modern best practices (fill gaps)
+4. Test-driven development using acceptance criteria
+
+**Timeline**: [Estimate based on codebase size]
+
+### Option 2: Incremental Refactoring
+1. **Strangler Pattern**: New implementation shadows old
+2. **Feature Flags**: Gradual traffic shift
+3. **Parallel Run**: Validate equivalence
+4. **Cutover**: Complete migration
+
+**Timeline**: [Estimate based on risk tolerance]
+
+## Improvement Opportunities
+
+### Technical Improvements
+- [ ] **Replace [Old Library]** with [Modern Alternative]
+  - **Rationale**: [Better performance, active maintenance]
+  - **Effort**: Medium
+
+- [ ] **Add [Missing Feature]**
+  - **Addresses Gap**: [Specific gap from analysis]
+  - **Effort**: High
+
+### Architectural Improvements
+- [ ] **Introduce Event Sourcing**
+  - **Enables**: Audit trail, event replay, temporal queries
+  - **Effort**: High
+
+- [ ] **Implement CQRS**
+  - **Separates**: Read and write models for optimization
+  - **Effort**: Medium
+
+### Operational Improvements
+- [ ] **CI/CD Pipeline**: Automated testing, deployment
+- [ ] **Infrastructure as Code**: Terraform, Pulumi
+- [ ] **Monitoring Dashboards**: Grafana, DataDog
+- [ ] **GitOps Deployment**: ArgoCD, Flux
+```
+
+---
+
+### Output 3: tasks.md
+
+Create actionable task breakdown:
+
+```markdown
+# [System Name] Implementation Tasks
+
+**Version**: 1.0 (Reverse Engineered)
+**Date**: [Date]
+
+## Overview
+
+This task breakdown represents how to rebuild this system from scratch using the specification and plan.
+
+**Estimated Timeline**: [X weeks based on team size]
+**Team Size**: [Assumed team composition]
+
+---
+
+## Phase 1: Core Infrastructure
+
+**Timeline**: Week 1
+**Dependencies**: None
+
+### Task 1.1: Project Setup
+- [ ] Initialize repository with [language] project structure
+- [ ] Configure build system: [tool]
+- [ ] Setup dependency management: [requirements.txt, package.json, go.mod]
+- [ ] Configure linting: [flake8, eslint, golangci-lint]
+- [ ] Setup pre-commit hooks
+- [ ] Create initial README
+
+### Task 1.2: Configuration System
+- [ ] Implement environment-based configuration
+- [ ] Support: Environment variables, config files, secrets management
+- [ ] Validation: Config schema validation on startup
+- [ ] Defaults: Sensible defaults for local development
+
+### Task 1.3: Logging Infrastructure
+- [ ] Setup structured logging (JSON format)
+- [ ] Configure log levels: DEBUG, INFO, WARN, ERROR
+- [ ] Add request correlation IDs
+- [ ] Integrate with [logging destination]
+
+---
+
+## Phase 2: Data Layer
+
+**Timeline**: Week 2-3
+**Dependencies**: Phase 1 complete
+
+### Task 2.1: Database Design
+- [ ] Design schema for entities: [User, Order, Product]
+- [ ] Define relationships: [one-to-many, many-to-many]
+- [ ] Add indexes for performance
+- [ ] Document schema in [ERD tool]
+
+### Task 2.2: ORM Setup
+- [ ] Install and configure [SQLAlchemy, Prisma, GORM]
+- [ ] Create model classes for all entities
+- [ ] Implement relationships
+- [ ] Add validation rules
+
+### Task 2.3: Migration System
+- [ ] Setup migration tool: [Alembic, Flyway, migrate]
+- [ ] Create initial migration
+- [ ] Document migration workflow
+- [ ] Add migration tests
+
+### Task 2.4: Repository Layer
+- [ ] Implement repository pattern for each entity
+- [ ] CRUD operations: Create, Read, Update, Delete
+- [ ] Query methods: FindByX, ListByY
+- [ ] Transaction management
+
+---
+
+## Phase 3: Business Logic Layer
+
+**Timeline**: Week 4-6
+**Dependencies**: Phase 2 complete
+
+### Task 3.1: [Feature A - e.g., User Authentication]
+- [ ] **Input validation**: Username/email, password strength
+- [ ] **Processing logic**:
+  - Hash password with bcrypt
+  - Generate JWT token
+  - Create user session
+- [ ] **Error handling**: Duplicate user, invalid credentials
+- [ ] **Output formatting**: User object + token
+
+### Task 3.2: [Feature B - e.g., Order Processing]
+- [ ] **Input validation**: Order items, quantities, payment info
+- [ ] **Processing logic**:
+  - Validate inventory availability
+  - Calculate totals, taxes, shipping
+  - Process payment via [Stripe]
+  - Update inventory
+  - Send confirmation
+- [ ] **Error handling**: Insufficient inventory, payment failed
+- [ ] **Output formatting**: Order confirmation
+
+[Continue for all major features discovered]
+
+---
+
+## Phase 4: API/Interface Layer
+
+**Timeline**: Week 7-8
+**Dependencies**: Phase 3 complete
+
+### Task 4.1: API Contract Definition
+- [ ] Design RESTful endpoints: [list all routes]
+- [ ] Define request schemas (OpenAPI/JSON Schema)
+- [ ] Define response schemas
+- [ ] Document error responses
+
+### Task 4.2: Controller Implementation
+- [ ] Implement route handlers
+- [ ] Input validation middleware
+- [ ] Auth middleware integration
+- [ ] Error handling middleware
+
+### Task 4.3: API Documentation
+- [ ] Generate OpenAPI/Swagger docs
+- [ ] Add usage examples
+- [ ] Document authentication flow
+- [ ] Create Postman collection
+
+---
+
+## Phase 5: Cross-Cutting Concerns
+
+**Timeline**: Week 9
+**Dependencies**: Phase 4 complete
+
+### Task 5.1: Authentication & Authorization
+- [ ] Implement JWT-based auth
+- [ ] Role-based access control (RBAC)
+- [ ] Token refresh mechanism
+- [ ] Session management
+
+### Task 5.2: Observability
+- [ ] **Metrics**: Instrument with [Prometheus, StatsD]
+  - Request rate, latency, error rate
+  - Business metrics: Orders/min, Revenue/hour
+- [ ] **Tracing**: Integrate [OpenTelemetry, Jaeger]
+  - Distributed tracing across services
+  - Performance bottleneck detection
+- [ ] **Health Checks**:
+  - `/health` - Liveness probe
+  - `/ready` - Readiness probe
+  - `/metrics` - Prometheus endpoint
+
+### Task 5.3: Error Handling
+- [ ] Global error handler
+- [ ] Structured error responses
+- [ ] Error logging with stack traces
+- [ ] Error monitoring integration
+
+### Task 5.4: Security Hardening
+- [ ] Input sanitization
+- [ ] SQL injection prevention
+- [ ] XSS protection
+- [ ] CSRF protection
+- [ ] Rate limiting
+- [ ] Security headers
+
+---
+
+## Phase 6: External Integrations
+
+**Timeline**: Week 10
+**Dependencies**: Phase 4 complete
+
+### Task 6.1: [Integration A - e.g., Payment Provider]
+- [ ] API client implementation
+- [ ] Retry logic with exponential backoff
+- [ ] Circuit breaker pattern
+- [ ] Webhook handling
+- [ ] Error recovery
+
+### Task 6.2: [Integration B - e.g., Email Service]
+- [ ] Template system
+- [ ] Async sending (queue-based)
+- [ ] Delivery tracking
+- [ ] Bounce handling
+
+[Continue for all external integrations]
+
+---
+
+## Phase 7: Testing & Quality
+
+**Timeline**: Week 11-12
+**Dependencies**: All phases complete
+
+### Task 7.1: Unit Tests
+- [ ] **Coverage target**: 80%+
+- [ ] **Framework**: [pytest, Jest, testing package]
+- [ ] Test all service methods
+- [ ] Test all repositories
+- [ ] Mock external dependencies
+
+### Task 7.2: Integration Tests
+- [ ] API endpoint tests
+- [ ] Database integration tests
+- [ ] External service integration tests (with mocks)
+- [ ] Test database setup/teardown
+
+### Task 7.3: End-to-End Tests
+- [ ] Critical user journeys:
+  - User registration → Login → Purchase → Logout
+  - [Other critical flows]
+- [ ] Test against staging environment
+- [ ] Automated with [Selenium, Playwright, Cypress]
+
+### Task 7.4: Performance Testing
+- [ ] Load testing: [k6, Locust, JMeter]
+- [ ] Stress testing: Find breaking points
+- [ ] Endurance testing: Memory leaks, connection exhaustion
+- [ ] Document performance baselines
+
+### Task 7.5: Security Testing
+- [ ] OWASP Top 10 vulnerability scan
+- [ ] Dependency vulnerability scan
+- [ ] Penetration testing (if budget allows)
+- [ ] Security code review
+
+---
+
+## Phase 8: Deployment & Operations
+
+**Timeline**: Week 13
+**Dependencies**: Phase 7 complete
+
+### Task 8.1: Containerization
+- [ ] Write production Dockerfile
+- [ ] Multi-stage build for optimization
+- [ ] Non-root user for security
+- [ ] Health check in container
+
+### Task 8.2: Kubernetes Manifests
+- [ ] Deployment manifest
+- [ ] Service manifest
+- [ ] ConfigMap for configuration
+- [ ] Secret for sensitive data
+- [ ] Ingress for routing
+- [ ] HorizontalPodAutoscaler
+
+### Task 8.3: CI/CD Pipeline
+- [ ] GitHub Actions / GitLab CI / Jenkins
+- [ ] Stages: Lint → Test → Build → Deploy
+- [ ] Automated testing in pipeline
+- [ ] Deployment to staging on merge to main
+- [ ] Manual approval for production
+
+### Task 8.4: Monitoring & Alerting
+- [ ] Setup Grafana dashboards
+- [ ] Configure alerts: Error rate spikes, latency increases
+- [ ] On-call rotation setup
+- [ ] Runbook documentation
+
+### Task 8.5: Documentation
+- [ ] Architecture documentation
+- [ ] API documentation
+- [ ] Deployment runbook
+- [ ] Troubleshooting guide
+- [ ] Onboarding guide for new developers
+
+---
+
+## Phase 9: Post-Launch
+
+**Timeline**: Ongoing
+**Dependencies**: Production deployment
+
+### Task 9.1: Monitoring & Incident Response
+- [ ] Monitor production metrics
+- [ ] Respond to alerts
+- [ ] Conduct post-mortems for incidents
+- [ ] Iterate on improvements
+
+### Task 9.2: Feature Iterations
+- [ ] Prioritize feature backlog
+- [ ] Implement high-priority features
+- [ ] A/B testing for new features
+- [ ] Gather user feedback
+
+### Task 9.3: Technical Debt Reduction
+- [ ] Address P0 gaps: [from gap analysis]
+- [ ] Address P1 gaps: [from gap analysis]
+- [ ] Refactor based on learnings
+- [ ] Update documentation
+```
+
+---
+
+### Output 4: intelligence-object.md
+
+Create reusable intelligence extraction:
+
+```markdown
+# [System Name] Reusable Intelligence
+
+**Version**: 1.0 (Extracted from Codebase)
+**Date**: [Date]
+
+## Overview
+
+This document captures the reusable intelligence embedded in the codebase—patterns, decisions, and expertise worth preserving and applying to future projects.
+
+---
+
+## Extracted Skills
+
+### Skill 1: [API Error Handling Strategy]
+
+**Persona**: You are a backend engineer designing resilient APIs that fail gracefully and provide actionable error information.
+
+**Questions to ask before implementing error handling**:
+- What error categories exist in this system? (Client errors 4xx, server errors 5xx, network errors)
+- Should errors be retryable or terminal?
+- What information helps debugging without exposing security details?
+- How do errors propagate through layers (API → Service → Data)?
+
+**Principles**:
+- **Never expose internal details**: Stack traces in development only, generic messages in production
+- **Consistent error schema**: All errors follow same structure `{error: {code, message, details, request_id}}`
+- **Log everything, return selectively**: Full context in logs, safe subset in API response
+- **Use HTTP status codes correctly**: 400 bad request, 401 unauthorized, 404 not found, 500 internal error
+- **Provide request IDs**: Enable correlation between client errors and server logs
+
+**Implementation Pattern** (observed in codebase):
+```python
+# Extracted from: [file: src/api/errors.py, lines 15-45]
+class APIError(Exception):
+    """Base exception for all API errors"""
+
+    def __init__(self, code: str, message: str, status: int = 400, details: dict = None):
+        self.code = code
+        self.message = message
+        self.status = status
+        self.details = details or {}
+
+    def to_response(self):
+        """Convert to JSON response format"""
+        return {
+            "error": {
+                "code": self.code,
+                "message": self.message,
+                "details": self.details,
+                "request_id": get_request_id(),
+                "timestamp": datetime.utcnow().isoformat()
+            }
+        }, self.status
+
+# Usage pattern:
+if not user:
+    raise APIError(
+        code="USER_NOT_FOUND",
+        message="User with specified ID does not exist",
+        status=404,
+        details={"user_id": user_id}
+    )
+```
+
+**When to apply**:
+- All API endpoints
+- Background jobs that report status
+- Any system with external-facing interfaces
+
+**Contraindications**:
+- Internal services (may prefer exceptions without HTTP semantics)
+- Real-time systems (error objects may be too heavy)
+
+---
+
+### Skill 2: [Database Connection Management]
+
+**Persona**: You are a backend engineer optimizing database performance through connection pooling and lifecycle management.
+
+**Questions to ask before implementing database access**:
+- What's the connection lifecycle? (Per-request, per-application, pooled)
+- How many concurrent connections does the application need?
+- What happens on connection failure? (Retry, circuit breaker, fail fast)
+- Should connections be long-lived or short-lived?
+
+**Principles**:
+- **Connection pooling is mandatory**: Never create connection per request (overhead)
+- **Pool size = 2 * CPU cores** (starting point, tune based on load)
+- **Idle timeout prevents resource leaks**: Close unused connections after [X] minutes
+- **Health checks detect stale connections**: Validate before use, not during query
+- **Graceful degradation**: Circuit breaker pattern when database unavailable
+
+**Implementation Pattern** (observed in codebase):
+```python
+# Extracted from: [file: src/db/connection.py, lines 20-55]
+from sqlalchemy import create_engine, pool
+
+# Connection pool configuration
+engine = create_engine(
+    DATABASE_URL,
+    poolclass=pool.QueuePool,
+    pool_size=10,              # Max connections in pool
+    max_overflow=20,           # Additional connections beyond pool_size
+    pool_timeout=30,           # Seconds to wait for connection
+    pool_recycle=3600,         # Recycle connections after 1 hour
+    pool_pre_ping=True,        # Test connection before using
+    echo=False                 # Don't log SQL (production)
+)
+
+# Context manager for connection lifecycle
+@contextmanager
+def get_db_session():
+    """Provide transactional scope around operations"""
+    session = Session(bind=engine)
+    try:
+        yield session
+        session.commit()
+    except Exception:
+        session.rollback()
+        raise
+    finally:
+        session.close()
+
+# Usage pattern:
+with get_db_session() as session:
+    user = session.query(User).filter_by(id=user_id).first()
+    # Connection automatically returned to pool on context exit
+```
+
+**When to apply**:
+- All database-backed applications
+- Services with moderate-to-high traffic
+- Long-running applications (not serverless functions)
+
+**Contraindications**:
+- Serverless/FaaS (use connection per invocation)
+- Very low-traffic applications (overhead not justified)
+
+---
+
+### Skill 3: [Input Validation Strategy]
+
+**Persona**: You are a security-focused engineer preventing injection attacks and data corruption through systematic input validation.
+
+**Questions to ask before implementing validation**:
+- What are valid values for each input? (type, range, format, length)
+- Where does validation occur? (Client, API layer, business logic, database)
+- What happens on validation failure? (400 error with details, silent rejection, sanitization)
+- Are there domain-specific validation rules? (email format, credit card format, etc.)
+
+**Principles**:
+- **Validate at boundaries**: API layer validates all external input
+- **Whitelist over blacklist**: Define allowed patterns, not forbidden ones
+- **Fail loudly on invalid input**: Return clear error messages (in dev/test), generic in prod
+- **Type validation first**: Check types before business rules
+- **Schema-based validation**: Use JSON Schema, Pydantic, Joi for declarative validation
+
+**Implementation Pattern** (observed in codebase):
+```python
+# Extracted from: [file: src/api/validators.py, lines 10-60]
+from pydantic import BaseModel, EmailStr, validator
+
+class CreateUserRequest(BaseModel):
+    """Validation schema for user creation"""
+    email: EmailStr                    # Email format validation
+    username: str
+    password: str
+    age: int
+
+    @validator('username')
+    def username_alphanumeric(cls, v):
+        """Username must be alphanumeric"""
+        if not v.isalnum():
+            raise ValueError('Username must contain only letters and numbers')
+        if len(v) < 3 or len(v) > 20:
+            raise ValueError('Username must be 3-20 characters')
+        return v
+
+    @validator('password')
+    def password_strength(cls, v):
+        """Password must meet strength requirements"""
+        if len(v) < 8:
+            raise ValueError('Password must be at least 8 characters')
+        if not any(c.isupper() for c in v):
+            raise ValueError('Password must contain uppercase letter')
+        if not any(c.isdigit() for c in v):
+            raise ValueError('Password must contain digit')
+        return v
+
+    @validator('age')
+    def age_range(cls, v):
+        """Age must be reasonable"""
+        if v < 13 or v > 120:
+            raise ValueError('Age must be between 13 and 120')
+        return v
+
+# Usage in API endpoint:
+@app.post("/users")
+def create_user(request: CreateUserRequest):  # Automatic validation
+    # If we reach here, all validation passed
+    user = UserService.create(request.dict())
+    return user.to_dict()
+```
+
+**When to apply**:
+- All API endpoints
+- All user input (forms, file uploads, etc.)
+- Configuration parsing
+- External data imports
+
+---
+
+[Continue with more skills extracted from codebase...]
+
+---
+
+## Architecture Decision Records (Inferred)
+
+### ADR-001: Choice of [PostgreSQL over MongoDB]
+
+**Status**: Accepted (inferred from implementation)
+
+**Context**:
+The system requires:
+- ACID transactions for order processing
+- Complex relational queries (joins across users, orders, products)
+- Data integrity guarantees
+- Mature ecosystem and tooling
+
+**Decision**: Use PostgreSQL as primary database
+
+**Rationale** (inferred from code patterns):
+1. **Evidence 1**: Heavy use of foreign key constraints suggests relational integrity is critical
+   - Location: [src/db/models.py, lines 45-120]
+   - Pattern: All entities have explicit FK relationships
+
+2. **Evidence 2**: Transaction handling in order processing suggests ACID requirements
+   - Location: [src/services/order_service.py, lines 200-250]
+   - Pattern: Multiple updates wrapped in single transaction
+
+3. **Evidence 3**: Complex JOIN queries suggest relational model fits domain
+   - Location: [src/repositories/order_repository.py, lines 80-150]
+   - Pattern: Multi-table joins for order + user + product data
+
+**Consequences**:
+
+**Positive**:
+- Strong data consistency guarantees
+- Rich query capabilities (window functions, CTEs)
+- JSON support for semi-structured data (best of both worlds)
+- Excellent tool ecosystem (pgAdmin, monitoring, backups)
+
+**Negative**:
+- Vertical scaling limits (eventual)
+- Schema migrations require planning
+- Not ideal for unstructured data
+
+**Alternatives Considered** (inferred):
+
+**MongoDB**:
+- **Rejected because**: Need for transactions and complex joins
+- **Evidence**: No document-oriented patterns in codebase
+
+**MySQL**:
+- **Rejected because**: PostgreSQL's superior JSON and full-text search
+- **Could have worked**: Similar feature set for this use case
+
+---
+
+### ADR-002: [JWT-based Authentication over Session Cookies]
+
+**Status**: Accepted (inferred from implementation)
+
+**Context**:
+The system needs:
+- Stateless authentication (for horizontal scaling)
+- Mobile app support (not browser-only)
+- Microservices architecture (shared auth across services)
+
+**Decision**: Use JWT tokens for authentication
+
+**Rationale** (inferred from code patterns):
+1. **Evidence 1**: No session storage implementation found
+   - Location: Absence of Redis/Memcached session store
+   - Pattern: No session management code
+
+2. **Evidence 2**: Token-based auth middleware
+   - Location: [src/middleware/auth.py, lines 10-50]
+   - Pattern: JWT decoding and validation
+
+3. **Evidence 3**: Token refresh endpoint
+   - Location: [src/api/auth.py, lines 100-130]
+   - Pattern: Refresh token rotation
+
+**Consequences**:
+
+**Positive**:
+- Stateless (no server-side session storage)
+- Scales horizontally (no session affinity)
+- Works across domains (CORS-friendly)
+- Mobile-app compatible
+
+**Negative**:
+- Cannot revoke tokens before expiry (mitigated with short TTL + refresh tokens)
+- Larger than session cookies (JWT payload in every request)
+- Vulnerable if secret key compromised
+
+**Mitigation Strategies** (observed):
+- Short access token TTL (15 minutes)
+- Refresh token rotation
+- Token blacklist for logout (stored in Redis)
+
+---
+
+[Continue with more ADRs...]
+
+---
+
+## Code Patterns & Conventions
+
+### Pattern 1: Repository Pattern for Data Access
+
+**Observed in**: All data layer modules
+
+**Structure**:
+```python
+class UserRepository:
+    """Abstract data access for User entity"""
+
+    def find_by_id(self, user_id: int) -> Optional[User]:
+        """Find user by ID"""
+        pass
+
+    def find_by_email(self, email: str) -> Optional[User]:
+        """Find user by email"""
+        pass
+
+    def create(self, user_data: dict) -> User:
+        """Create new user"""
+        pass
+
+    def update(self, user_id: int, updates: dict) -> User:
+        """Update existing user"""
+        pass
+
+    def delete(self, user_id: int) -> bool:
+        """Soft-delete user"""
+        pass
+```
+
+**Benefits**:
+- Decouples business logic from data access
+- Testable (can mock repositories)
+- Swappable implementations (SQL → NoSQL)
+
+**When to apply**: All entity persistence
+
+---
+
+### Pattern 2: Service Layer for Business Logic
+
+**Observed in**: All business logic modules
+
+**Structure**:
+```python
+class OrderService:
+    """Business logic for order processing"""
+
+    def __init__(self, order_repo, inventory_service, payment_service):
+        self.order_repo = order_repo
+        self.inventory_service = inventory_service
+        self.payment_service = payment_service
+
+    def create_order(self, user_id: int, items: List[OrderItem]) -> Order:
+        """
+        Create order with inventory validation and payment processing
+
+        Steps:
+        1. Validate inventory availability
+        2. Calculate totals
+        3. Process payment
+        4. Create order record
+        5. Update inventory
+        6. Send confirmation
+        """
+        # Orchestration logic here
+        pass
+```
+
+**Benefits**:
+- Encapsulates business rules
+- Coordinates multiple repositories/services
+- Transactional boundary
+
+**When to apply**: All complex business operations
+
+---
+
+## Lessons Learned
+
+### What Worked Well
+
+1. **Clear layer separation**
+   - Controllers stayed thin (routing only)
+   - Services contained business logic
+   - Repositories isolated data access
+   - **Benefit**: Easy to test, easy to reason about
+
+2. **Comprehensive input validation**
+   - Schema-based validation at API boundary
+   - Early failure with clear error messages
+   - **Benefit**: Prevented data corruption, improved debugging
+
+3. **Structured logging**
+   - JSON format with correlation IDs
+   - Consistent log levels
+   - **Benefit**: Effective debugging in production
+
+### What Could Be Improved
+
+1. **Missing integration tests**
+   - Lots of unit tests, few integration tests
+   - **Impact**: Bugs in component interactions not caught early
+   - **Recommendation**: Add integration test suite
+
+2. **Inconsistent error handling**
+   - Some modules use custom exceptions, others use generic
+   - **Impact**: Harder to handle errors consistently
+   - **Recommendation**: Standardize on error handling strategy
+
+3. **Undocumented API contracts**
+   - No OpenAPI/Swagger documentation
+   - **Impact**: Frontend developers had to read code
+   - **Recommendation**: Generate API docs from code
+
+### What to Avoid in Future Projects
+
+1. **Hardcoded configuration**
+   - Some settings hardcoded instead of environment variables
+   - **Why bad**: Requires code changes for deployment differences
+   - **Alternative**: 12-factor app configuration
+
+2. **Tight coupling to external services**
+   - Direct API calls without abstraction layer
+   - **Why bad**: Hard to swap providers, hard to test
+   - **Alternative**: Adapter pattern for external integrations
+
+3. **Missing observability**
+   - No metrics, basic logging only
+   - **Why bad**: Blind to production issues
+   - **Alternative**: Metrics + tracing + structured logs from day 1
+
+---
+
+## Reusability Assessment
+
+### Components Reusable As-Is
+
+1. **Error handling framework** → Portable to any API project
+2. **Database connection pooling** → Portable to any DB-backed service
+3. **JWT authentication middleware** → Portable to any auth scenario
+4. **Input validation schemas** → Patterns reusable, specifics domain-dependent
+
+### Patterns Worth Generalizing
+
+1. **Repository pattern** → Create skill/template for any entity
+2. **Service orchestration** → Create skill for multi-step business logic
+3. **API error responses** → Create skill for consistent error handling
+
+### Domain-Specific (Not Reusable)
+
+1. **Order processing logic** → Specific to e-commerce domain
+2. **Inventory management** → Specific to this business
+3. **Payment integration** → Specific to Stripe, but pattern reusable
+```
+
+---
+
+## Final Validation Checklist
+
+Before submitting outputs, verify:
+
+- [ ] **spec.md is complete**: Can regenerate system from spec alone?
+- [ ] **plan.md is coherent**: Does architecture make sense given requirements?
+- [ ] **tasks.md is actionable**: Can team execute without additional guidance?
+- [ ] **intelligence-object.md is reusable**: Can skills apply to other projects?
+- [ ] **All files cross-reference**: Spec → Plan → Tasks flow logically?
+- [ ] **Evidence provided**: All claims backed by code locations (file:line)?
+- [ ] **Gaps identified**: Technical debt and improvements documented?
+- [ ] **Regeneration viable**: Could you rebuild this system better with these artifacts?
+
+---
+
+## Self-Monitoring: Anti-Convergence for Archaeologists
+
+**You tend to converge toward**:
+- ✅ Surface-level analysis (reading code without understanding intent)
+- ✅ Feature enumeration (listing WHAT without inferring WHY)
+- ✅ Copy-paste specs (documenting existing vs imagining ideal)
+- ✅ Generic patterns (not extracting codebase-specific intelligence)
+
+**Activate reasoning by asking**:
+- "If I rewrote this from scratch, would my spec produce equivalent system?"
+- "What tacit knowledge is embedded in this code that isn't written down?"
+- "Why did the original developers make these specific choices?"
+- "What would I do differently if building this today?"
+
+**Your reverse engineering succeeds when**:
+- Spec is complete enough to regenerate system
+- Plan reveals architectural reasoning, not just structure
+- Tasks are actionable for new team unfamiliar with codebase
+- Intelligence extracted is reusable beyond this specific system
+- Gaps identified with clear remediation path
+- You can articulate WHY decisions were made, not just WHAT was implemented
+
+---
+
+## Output Location
+
+Save all artifacts to:
+```
+[codebase-path]/docs/reverse-engineered/
+├── spec.md
+├── plan.md
+├── tasks.md
+└── intelligence-object.md
+```
+
+Or user-specified location.
+
+---
+
+**Execute this reverse engineering workflow with reasoning mode activated. Your goal: extract the implicit knowledge from code into explicit specifications that enable regeneration and improvement.**
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.specify.md

@@ -0,0 +1,284 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+handoffs: 
+  - label: Build Technical Plan
+    agent: sp.plan
+    prompt: Create a plan for the spec. I am building with...
+  - label: Clarify Spec Requirements
+    agent: sp.clarify
+    prompt: Clarify specification requirements
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+The text the user typed after `/sp.specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. **Generate a concise short name** (2-4 words) for the branch:
+   - Analyze the feature description and extract the most meaningful keywords
+   - Create a 2-4 word short name that captures the essence of the feature
+   - Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
+   - Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
+   - Keep it concise but descriptive enough to understand the feature at a glance
+   - Examples:
+     - "I want to add user authentication" → "user-auth"
+     - "Implement OAuth2 integration for the API" → "oauth2-api-integration"
+     - "Create a dashboard for analytics" → "analytics-dashboard"
+     - "Fix payment processing timeout bug" → "fix-payment-timeout"
+
+2. **Check for existing branches before creating new one**:
+
+   a. First, fetch all remote branches to ensure we have the latest information:
+
+      ```bash
+      git fetch --all --prune
+      ```
+
+   b. Find the highest feature number across all sources for the short-name:
+      - Remote branches: `git ls-remote --heads origin | grep -E 'refs/heads/[0-9]+-<short-name>$'`
+      - Local branches: `git branch | grep -E '^[* ]*[0-9]+-<short-name>$'`
+      - Specs directories: Check for directories matching `specs/[0-9]+-<short-name>`
+
+   c. Determine the next available number:
+      - Extract all numbers from all three sources
+      - Find the highest number N
+      - Use N+1 for the new branch number
+
+   d. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` with the calculated number and short-name:
+      - Pass `--number N+1` and `--short-name "your-short-name"` along with the feature description
+      - Bash example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" --json --number 5 --short-name "user-auth" "Add user authentication"`
+      - PowerShell example: `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS" -Json -Number 5 -ShortName "user-auth" "Add user authentication"`
+
+   **IMPORTANT**:
+   - Check all three sources (remote branches, local branches, specs directories) to find the highest number
+   - Only match branches/directories with the exact short-name pattern
+   - If no existing branches/directories found with this short-name, start with number 1
+   - You must only ever run this script once per feature
+   - The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for
+   - The JSON output will contain BRANCH_NAME and SPEC_FILE paths
+   - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot")
+
+3. Load `.specify/templates/spec-template.md` to understand required sections.
+
+4. Follow this execution flow:
+
+    1. Parse user description from Input
+       If empty: ERROR "No feature description provided"
+    2. Extract key concepts from description
+       Identify: actors, actions, data, constraints
+    3. For unclear aspects:
+       - Make informed guesses based on context and industry standards
+       - Only mark with [NEEDS CLARIFICATION: specific question] if:
+         - The choice significantly impacts feature scope or user experience
+         - Multiple reasonable interpretations exist with different implications
+         - No reasonable default exists
+       - **LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total**
+       - Prioritize clarifications by impact: scope > security/privacy > user experience > technical details
+    4. Fill User Scenarios & Testing section
+       If no clear user flow: ERROR "Cannot determine user scenarios"
+    5. Generate Functional Requirements
+       Each requirement must be testable
+       Use reasonable defaults for unspecified details (document assumptions in Assumptions section)
+    6. Define Success Criteria
+       Create measurable, technology-agnostic outcomes
+       Include both quantitative metrics (time, performance, volume) and qualitative measures (user satisfaction, task completion)
+       Each criterion must be verifiable without implementation details
+    7. Identify Key Entities (if data involved)
+    8. Return: SUCCESS (spec ready for planning)
+
+5. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+
+6. **Specification Quality Validation**: After writing the initial spec, validate it against quality criteria:
+
+   a. **Create Spec Quality Checklist**: Generate a checklist file at `FEATURE_DIR/checklists/requirements.md` using the checklist template structure with these validation items:
+
+      ```markdown
+      # Specification Quality Checklist: [FEATURE NAME]
+      
+      **Purpose**: Validate specification completeness and quality before proceeding to planning
+      **Created**: [DATE]
+      **Feature**: [Link to spec.md]
+      
+      ## Content Quality
+      
+      - [ ] No implementation details (languages, frameworks, APIs)
+      - [ ] Focused on user value and business needs
+      - [ ] Written for non-technical stakeholders
+      - [ ] All mandatory sections completed
+      
+      ## Requirement Completeness
+      
+      - [ ] No [NEEDS CLARIFICATION] markers remain
+      - [ ] Requirements are testable and unambiguous
+      - [ ] Success criteria are measurable
+      - [ ] Success criteria are technology-agnostic (no implementation details)
+      - [ ] All acceptance scenarios are defined
+      - [ ] Edge cases are identified
+      - [ ] Scope is clearly bounded
+      - [ ] Dependencies and assumptions identified
+      
+      ## Feature Readiness
+      
+      - [ ] All functional requirements have clear acceptance criteria
+      - [ ] User scenarios cover primary flows
+      - [ ] Feature meets measurable outcomes defined in Success Criteria
+      - [ ] No implementation details leak into specification
+      
+      ## Notes
+      
+      - Items marked incomplete require spec updates before `/sp.clarify` or `/sp.plan`
+      ```
+
+   b. **Run Validation Check**: Review the spec against each checklist item:
+      - For each item, determine if it passes or fails
+      - Document specific issues found (quote relevant spec sections)
+
+   c. **Handle Validation Results**:
+
+      - **If all items pass**: Mark checklist complete and proceed to step 6
+
+      - **If items fail (excluding [NEEDS CLARIFICATION])**:
+        1. List the failing items and specific issues
+        2. Update the spec to address each issue
+        3. Re-run validation until all items pass (max 3 iterations)
+        4. If still failing after 3 iterations, document remaining issues in checklist notes and warn user
+
+      - **If [NEEDS CLARIFICATION] markers remain**:
+        1. Extract all [NEEDS CLARIFICATION: ...] markers from the spec
+        2. **LIMIT CHECK**: If more than 3 markers exist, keep only the 3 most critical (by scope/security/UX impact) and make informed guesses for the rest
+        3. For each clarification needed (max 3), present options to user in this format:
+
+           ```markdown
+           ## Question [N]: [Topic]
+           
+           **Context**: [Quote relevant spec section]
+           
+           **What we need to know**: [Specific question from NEEDS CLARIFICATION marker]
+           
+           **Suggested Answers**:
+           
+           | Option | Answer | Implications |
+           |--------|--------|--------------|
+           | A      | [First suggested answer] | [What this means for the feature] |
+           | B      | [Second suggested answer] | [What this means for the feature] |
+           | C      | [Third suggested answer] | [What this means for the feature] |
+           | Custom | Provide your own answer | [Explain how to provide custom input] |
+           
+           **Your choice**: _[Wait for user response]_
+           ```
+
+        4. **CRITICAL - Table Formatting**: Ensure markdown tables are properly formatted:
+           - Use consistent spacing with pipes aligned
+           - Each cell should have spaces around content: `| Content |` not `|Content|`
+           - Header separator must have at least 3 dashes: `|--------|`
+           - Test that the table renders correctly in markdown preview
+        5. Number questions sequentially (Q1, Q2, Q3 - max 3 total)
+        6. Present all questions together before waiting for responses
+        7. Wait for user to respond with their choices for all questions (e.g., "Q1: A, Q2: Custom - [details], Q3: B")
+        8. Update the spec by replacing each [NEEDS CLARIFICATION] marker with the user's selected or provided answer
+        9. Re-run validation after all clarifications are resolved
+
+   d. **Update Checklist**: After each validation iteration, update the checklist file with current pass/fail status
+
+7. Report completion with branch name, spec file path, checklist results, and readiness for the next phase (`/sp.clarify` or `/sp.plan`).
+
+**NOTE:** The script creates and checks out the new branch and initializes the spec file before writing.
+
+## General Guidelines
+
+## Quick Guidelines
+
+- Focus on **WHAT** users need and **WHY**.
+- Avoid HOW to implement (no tech stack, APIs, code structure).
+- Written for business stakeholders, not developers.
+- DO NOT create any checklists that are embedded in the spec. That will be a separate command.
+
+### Section Requirements
+
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+
+When creating this spec from a user prompt:
+
+1. **Make informed guesses**: Use context, industry standards, and common patterns to fill gaps
+2. **Document assumptions**: Record reasonable defaults in the Assumptions section
+3. **Limit clarifications**: Maximum 3 [NEEDS CLARIFICATION] markers - use only for critical decisions that:
+   - Significantly impact feature scope or user experience
+   - Have multiple reasonable interpretations with different implications
+   - Lack any reasonable default
+4. **Prioritize clarifications**: scope > security/privacy > user experience > technical details
+5. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+6. **Common areas needing clarification** (only if no reasonable default exists):
+   - Feature scope and boundaries (include/exclude specific use cases)
+   - User types and permissions (if multiple conflicting interpretations possible)
+   - Security/compliance requirements (when legally/financially significant)
+
+**Examples of reasonable defaults** (don't ask about these):
+
+- Data retention: Industry-standard practices for the domain
+- Performance targets: Standard web/mobile app expectations unless specified
+- Error handling: User-friendly messages with appropriate fallbacks
+- Authentication method: Standard session-based or OAuth2 for web apps
+- Integration patterns: RESTful APIs unless specified otherwise
+
+### Success Criteria Guidelines
+
+Success criteria must be:
+
+1. **Measurable**: Include specific metrics (time, percentage, count, rate)
+2. **Technology-agnostic**: No mention of frameworks, languages, databases, or tools
+3. **User-focused**: Describe outcomes from user/business perspective, not system internals
+4. **Verifiable**: Can be tested/validated without knowing implementation details
+
+**Good examples**:
+
+- "Users can complete checkout in under 3 minutes"
+- "System supports 10,000 concurrent users"
+- "95% of searches return results in under 1 second"
+- "Task completion rate improves by 40%"
+
+**Bad examples** (implementation-focused):
+
+- "API response time is under 200ms" (too technical, use "Users see results instantly")
+- "Database can handle 1000 TPS" (implementation detail, use user-facing metric)
+- "React components render efficiently" (framework-specific)
+- "Redis cache hit rate above 80%" (technology-specific)
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.tasks.md

@@ -0,0 +1,163 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+handoffs: 
+  - label: Analyze For Consistency
+    agent: sp.analyze
+    prompt: Run a project analysis for consistency
+    send: true
+  - label: Implement Project
+    agent: sp.implement
+    prompt: Start the implementation in phases
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. **Setup**: Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+
+2. **Load design documents**: Read from FEATURE_DIR:
+   - **Required**: plan.md (tech stack, libraries, structure), spec.md (user stories with priorities)
+   - **Optional**: data-model.md (entities), contracts/ (API endpoints), research.md (decisions), quickstart.md (test scenarios)
+   - Note: Not all projects have all documents. Generate tasks based on what's available.
+
+3. **Execute task generation workflow**:
+   - Load plan.md and extract tech stack, libraries, project structure
+   - Load spec.md and extract user stories with their priorities (P1, P2, P3, etc.)
+   - If data-model.md exists: Extract entities and map to user stories
+   - If contracts/ exists: Map endpoints to user stories
+   - If research.md exists: Extract decisions for setup tasks
+   - Generate tasks organized by user story (see Task Generation Rules below)
+   - Generate dependency graph showing user story completion order
+   - Create parallel execution examples per user story
+   - Validate task completeness (each user story has all needed tasks, independently testable)
+
+4. **Generate tasks.md**: Use `.specify/templates/tasks-template.md` as structure, fill with:
+   - Correct feature name from plan.md
+   - Phase 1: Setup tasks (project initialization)
+   - Phase 2: Foundational tasks (blocking prerequisites for all user stories)
+   - Phase 3+: One phase per user story (in priority order from spec.md)
+   - Each phase includes: story goal, independent test criteria, tests (if requested), implementation tasks
+   - Final Phase: Polish & cross-cutting concerns
+   - All tasks must follow the strict checklist format (see Task Generation Rules below)
+   - Clear file paths for each task
+   - Dependencies section showing story completion order
+   - Parallel execution examples per story
+   - Implementation strategy section (MVP first, incremental delivery)
+
+5. **Report**: Output path to generated tasks.md and summary:
+   - Total task count
+   - Task count per user story
+   - Parallel opportunities identified
+   - Independent test criteria for each story
+   - Suggested MVP scope (typically just User Story 1)
+   - Format validation: Confirm ALL tasks follow the checklist format (checkbox, ID, labels, file paths)
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
+
+## Task Generation Rules
+
+**CRITICAL**: Tasks MUST be organized by user story to enable independent implementation and testing.
+
+**Tests are OPTIONAL**: Only generate test tasks if explicitly requested in the feature specification or if user requests TDD approach.
+
+### Checklist Format (REQUIRED)
+
+Every task MUST strictly follow this format:
+
+```text
+- [ ] [TaskID] [P?] [Story?] Description with file path
+```
+
+**Format Components**:
+
+1. **Checkbox**: ALWAYS start with `- [ ]` (markdown checkbox)
+2. **Task ID**: Sequential number (T001, T002, T003...) in execution order
+3. **[P] marker**: Include ONLY if task is parallelizable (different files, no dependencies on incomplete tasks)
+4. **[Story] label**: REQUIRED for user story phase tasks only
+   - Format: [US1], [US2], [US3], etc. (maps to user stories from spec.md)
+   - Setup phase: NO story label
+   - Foundational phase: NO story label  
+   - User Story phases: MUST have story label
+   - Polish phase: NO story label
+5. **Description**: Clear action with exact file path
+
+**Examples**:
+
+- ✅ CORRECT: `- [ ] T001 Create project structure per implementation plan`
+- ✅ CORRECT: `- [ ] T005 [P] Implement authentication middleware in src/middleware/auth.py`
+- ✅ CORRECT: `- [ ] T012 [P] [US1] Create User model in src/models/user.py`
+- ✅ CORRECT: `- [ ] T014 [US1] Implement UserService in src/services/user_service.py`
+- ❌ WRONG: `- [ ] Create User model` (missing ID and Story label)
+- ❌ WRONG: `T001 [US1] Create model` (missing checkbox)
+- ❌ WRONG: `- [ ] [US1] Create User model` (missing Task ID)
+- ❌ WRONG: `- [ ] T001 [US1] Create model` (missing file path)
+
+### Task Organization
+
+1. **From User Stories (spec.md)** - PRIMARY ORGANIZATION:
+   - Each user story (P1, P2, P3...) gets its own phase
+   - Map all related components to their story:
+     - Models needed for that story
+     - Services needed for that story
+     - Endpoints/UI needed for that story
+     - If tests requested: Tests specific to that story
+   - Mark story dependencies (most stories should be independent)
+
+2. **From Contracts**:
+   - Map each contract/endpoint → to the user story it serves
+   - If tests requested: Each contract → contract test task [P] before implementation in that story's phase
+
+3. **From Data Model**:
+   - Map each entity to the user story(ies) that need it
+   - If entity serves multiple stories: Put in earliest story or Setup phase
+   - Relationships → service layer tasks in appropriate story phase
+
+4. **From Setup/Infrastructure**:
+   - Shared infrastructure → Setup phase (Phase 1)
+   - Foundational/blocking tasks → Foundational phase (Phase 2)
+   - Story-specific setup → within that story's phase
+
+### Phase Structure
+
+- **Phase 1**: Setup (project initialization)
+- **Phase 2**: Foundational (blocking prerequisites - MUST complete before user stories)
+- **Phase 3+**: User Stories in priority order (P1, P2, P3...)
+  - Within each story: Tests (if requested) → Models → Services → Endpoints → Integration
+  - Each phase should be a complete, independently testable increment
+- **Final Phase**: Polish & Cross-Cutting Concerns
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.claude/commands/sp.taskstoissues.md

@@ -0,0 +1,56 @@
+---
+description: Convert existing tasks into actionable, dependency-ordered GitHub issues for the feature based on available design artifacts.
+tools: ['github/github-mcp-server/issue_write']
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Outline
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
+1. From the executed script, extract the path to **tasks**.
+1. Get the Git remote by running:
+
+```bash
+git config --get remote.origin.url
+```
+
+> [!CAUTION]
+> ONLY PROCEED TO NEXT STEPS IF THE REMOTE IS A GITHUB URL
+
+1. For each task in the list, use the GitHub MCP server to create a new issue in the repository that is representative of the Git remote.
+
+> [!CAUTION]
+> UNDER NO CIRCUMSTANCES EVER CREATE ISSUES IN REPOSITORIES THAT DO NOT MATCH THE REMOTE URL
+
+---
+
+As the main request completes, you MUST create and complete a PHR (Prompt History Record) using agent‑native tools when possible.
+
+1) Determine Stage
+   - Stage: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate Title and Determine Routing:
+   - Generate Title: 3–7 words (slug for filename)
+   - Route is automatically determined by stage:
+     - `constitution` → `history/prompts/constitution/`
+     - Feature stages → `history/prompts/<feature-name>/` (spec, plan, tasks, red, green, refactor, explainer, misc)
+     - `general` → `history/prompts/general/`
+
+3) Create and Fill PHR (Shell first; fallback agent‑native)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Open the file and fill remaining placeholders (YAML + body), embedding full PROMPT_TEXT (verbatim) and concise RESPONSE_TEXT.
+   - If the script fails:
+     - Read `.specify/templates/phr-template.prompt.md` (or `templates/…`)
+     - Allocate an ID; compute the output path based on stage from step 2; write the file
+     - Fill placeholders and embed full PROMPT_TEXT and concise RESPONSE_TEXT
+
+4) Validate + report
+   - No unresolved placeholders; path under `history/prompts/` and matches stage; stage/title/date coherent; print ID + path + stage + title.
+   - On failure: warn, don't block. Skip only for `/sp.phr`.

.dockerignore

@@ -0,0 +1,22 @@
+**/.git
+**/.gitignore
+**/node_modules
+**/__pycache__
+**/*.pyc
+**/.pytest_cache
+**/.env
+**/.env.*
+**/venv
+**/venv_linux
+**/.next
+**/uploads/*
+**/*.log
+**/.DS_Store
+phase-2-ai-engine
+phase-3-approval-system
+phase-4-learning-loop
+phase-5-video-engine
+phase-6-saas-core
+docs
+history
+specs

.gitattributes

@@ -0,0 +1,2 @@
+*.woff2 filter=lfs diff=lfs merge=lfs -text
+*.woff filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,49 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+venv/
+venv_linux/
+env/
+.env
+.env.*
+!.env.example
+# Node.js
+node_modules/
+.next/
+out/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+*.log
+frontend_output.log
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+# Uploads (user data)
+uploads/
+*.png
+*.jpg
+*.jpeg
+*.mp4
+*.mov
+# Local config
+*.local
+settings.local.json
+# Misc
+mcp-shell.log
+*.bak
+phase-1-core-infra/frontend/.next/standalone
+phase-1-core-infra/frontend/.next/cache

.specify/memory/constitution.md

@@ -0,0 +1,55 @@
+# [PROJECT_NAME] Constitution
+<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+
+## Core Principles
+
+### [PRINCIPLE_1_NAME]
+<!-- Example: I. Library-First -->
+[PRINCIPLE_1_DESCRIPTION]
+<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+
+### [PRINCIPLE_2_NAME]
+<!-- Example: II. CLI Interface -->
+[PRINCIPLE_2_DESCRIPTION]
+<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+
+### [PRINCIPLE_3_NAME]
+<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
+[PRINCIPLE_3_DESCRIPTION]
+<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+
+### [PRINCIPLE_4_NAME]
+<!-- Example: IV. Integration Testing -->
+[PRINCIPLE_4_DESCRIPTION]
+<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+
+### [PRINCIPLE_5_NAME]
+<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
+[PRINCIPLE_5_DESCRIPTION]
+<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+
+### [PRINCIPLE_6_NAME]
+
+
+[PRINCIPLE__DESCRIPTION]
+
+## [SECTION_2_NAME]
+<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+
+[SECTION_2_CONTENT]
+<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+
+## [SECTION_3_NAME]
+<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+
+[SECTION_3_CONTENT]
+<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+
+## Governance
+<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
+
+[GOVERNANCE_RULES]
+<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+
+**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
+<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->

.specify/scripts/bash/check-prerequisites.sh

@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /sp.specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /sp.plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /sp.tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi

.specify/scripts/bash/common.sh

@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+# Find feature directory by numeric prefix instead of exact branch match
+# This allows multiple branches to work on the same spec (e.g., 004-fix-bug, 004-add-feature)
+find_feature_dir_by_prefix() {
+    local repo_root="$1"
+    local branch_name="$2"
+    local specs_dir="$repo_root/specs"
+
+    # Extract numeric prefix from branch (e.g., "004" from "004-whatever")
+    if [[ ! "$branch_name" =~ ^([0-9]{3})- ]]; then
+        # If branch doesn't have numeric prefix, fall back to exact match
+        echo "$specs_dir/$branch_name"
+        return
+    fi
+
+    local prefix="${BASH_REMATCH[1]}"
+
+    # Search for directories in specs/ that start with this prefix
+    local matches=()
+    if [[ -d "$specs_dir" ]]; then
+        for dir in "$specs_dir"/"$prefix"-*; do
+            if [[ -d "$dir" ]]; then
+                matches+=("$(basename "$dir")")
+            fi
+        done
+    fi
+
+    # Handle results
+    if [[ ${#matches[@]} -eq 0 ]]; then
+        # No match found - return the branch name path (will fail later with clear error)
+        echo "$specs_dir/$branch_name"
+    elif [[ ${#matches[@]} -eq 1 ]]; then
+        # Exactly one match - perfect!
+        echo "$specs_dir/${matches[0]}"
+    else
+        # Multiple matches - this shouldn't happen with proper naming convention
+        echo "ERROR: Multiple spec directories found with prefix '$prefix': ${matches[*]}" >&2
+        echo "Please ensure only one spec directory exists per numeric prefix." >&2
+        echo "$specs_dir/$branch_name"  # Return something to avoid breaking the script
+    fi
+}
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+
+    if has_git; then
+        has_git_repo="true"
+    fi
+
+    # Use prefix-based lookup to support multiple branches per spec
+    local feature_dir=$(find_feature_dir_by_prefix "$repo_root" "$current_branch")
+
+    cat <<EOF
+REPO_ROOT='$repo_root'
+CURRENT_BRANCH='$current_branch'
+HAS_GIT='$has_git_repo'
+FEATURE_DIR='$feature_dir'
+FEATURE_SPEC='$feature_dir/spec.md'
+IMPL_PLAN='$feature_dir/plan.md'
+TASKS='$feature_dir/tasks.md'
+RESEARCH='$feature_dir/research.md'
+DATA_MODEL='$feature_dir/data-model.md'
+QUICKSTART='$feature_dir/quickstart.md'
+CONTRACTS_DIR='$feature_dir/contracts'
+EOF
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+

.specify/scripts/bash/create-adr.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# create-adr.sh - Create a new Architecture Decision Record deterministically
+#
+# This script ONLY:
+#   1. Creates the correct directory structure (history/adr/)
+#   2. Copies the template with {{PLACEHOLDERS}} intact
+#   3. Returns metadata (id, path) for AI to fill in
+#
+# The calling AI agent is responsible for filling {{PLACEHOLDERS}}
+#
+# Usage:
+#   scripts/bash/create-adr.sh \
+#     --title "Use WebSockets for Real-time Chat" \
+#     [--json]
+
+JSON=false
+TITLE=""
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON=true; shift ;;
+    --title) TITLE=${2:-}; shift 2 ;;
+    --help|-h)
+      cat <<EOF
+Usage: $0 --title <title> [options]
+
+Required:
+  --title <text>       Title for the ADR (used for filename)
+
+Optional:
+  --json               Output JSON with id and path
+
+Output:
+  Creates ADR file with template placeholders ({{ID}}, {{TITLE}}, etc.)
+  AI agent must fill these placeholders after creation
+
+Examples:
+  $0 --title "Use WebSockets for Real-time Chat" --json
+  $0 --title "Adopt PostgreSQL for Primary Database"
+EOF
+      exit 0
+      ;;
+    *) shift ;;
+  esac
+done
+
+if [[ -z "$TITLE" ]]; then
+  echo "Error: --title is required" >&2
+  exit 1
+fi
+
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+ADR_DIR="$REPO_ROOT/history/adr"
+mkdir -p "$ADR_DIR"
+
+# Check for template (try both locations)
+TPL=""
+if [[ -f "$REPO_ROOT/.specify/templates/adr-template.md" ]]; then
+  TPL="$REPO_ROOT/.specify/templates/adr-template.md"
+elif [[ -f "$REPO_ROOT/templates/adr-template.md" ]]; then
+  TPL="$REPO_ROOT/templates/adr-template.md"
+else
+  echo "Error: ADR template not found at .specify/templates/ or templates/" >&2
+  exit 1
+fi
+
+# next id
+next_id() {
+  local max=0 base num
+  shopt -s nullglob
+  for f in "$ADR_DIR"/[0-9][0-9][0-9][0-9]-*.md; do
+    base=$(basename "$f")
+    num=${base%%-*}
+    if [[ $num =~ ^[0-9]{4}$ ]]; then
+      local n=$((10#$num))
+      (( n > max )) && max=$n
+    fi
+  done
+  printf "%04d" $((max+1))
+}
+
+slugify() {
+  echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g; s/-\{2,\}/-/g; s/^-//; s/-$//'
+}
+
+ID=$(next_id)
+SLUG=$(slugify "$TITLE")
+OUTFILE="$ADR_DIR/${ID}-${SLUG}.md"
+
+# Simply copy the template (AI will fill placeholders)
+cp "$TPL" "$OUTFILE"
+
+ABS=$(cd "$(dirname "$OUTFILE")" && pwd)/$(basename "$OUTFILE")
+if $JSON; then
+  printf '{"id":"%s","path":"%s","template":"%s"}\n' "$ID" "$ABS" "$(basename "$TPL")"
+else
+  echo "✅ ADR template copied → $ABS"
+  echo "Note: AI agent should now fill in {{PLACEHOLDERS}}"
+fi

.specify/scripts/bash/create-new-feature.sh

@@ -0,0 +1,302 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+SHORT_NAME=""
+BRANCH_NUMBER=""
+ARGS=()
+i=1
+while [ $i -le $# ]; do
+    arg="${!i}"
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --short-name)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            # Check if the next argument is another option (starts with --)
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --short-name requires a value' >&2
+                exit 1
+            fi
+            SHORT_NAME="$next_arg"
+            ;;
+        --number)
+            if [ $((i + 1)) -gt $# ]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            i=$((i + 1))
+            next_arg="${!i}"
+            if [[ "$next_arg" == --* ]]; then
+                echo 'Error: --number requires a value' >&2
+                exit 1
+            fi
+            BRANCH_NUMBER="$next_arg"
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
+            echo ""
+            echo "Options:"
+            echo "  --json              Output in JSON format"
+            echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
+            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --help, -h          Show this help message"
+            echo ""
+            echo "Examples:"
+            echo "  $0 'Add user authentication system' --short-name 'user-auth'"
+            echo "  $0 'Implement OAuth2 integration for API' --number 5"
+            exit 0
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+    i=$((i + 1))
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Function to get highest number from specs directory
+get_highest_from_specs() {
+    local specs_dir="$1"
+    local highest=0
+    
+    if [ -d "$specs_dir" ]; then
+        for dir in "$specs_dir"/*; do
+            [ -d "$dir" ] || continue
+            dirname=$(basename "$dir")
+            number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+            number=$((10#$number))
+            if [ "$number" -gt "$highest" ]; then
+                highest=$number
+            fi
+        done
+    fi
+    
+    echo "$highest"
+}
+
+# Function to get highest number from git branches
+get_highest_from_branches() {
+    local highest=0
+    
+    # Get all branches (local and remote)
+    branches=$(git branch -a 2>/dev/null || echo "")
+    
+    if [ -n "$branches" ]; then
+        while IFS= read -r branch; do
+            # Clean branch name: remove leading markers and remote prefixes
+            clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+            
+            # Extract feature number if branch matches pattern ###-*
+            if echo "$clean_branch" | grep -q '^[0-9]\{3\}-'; then
+                number=$(echo "$clean_branch" | grep -o '^[0-9]\{3\}' || echo "0")
+                number=$((10#$number))
+                if [ "$number" -gt "$highest" ]; then
+                    highest=$number
+                fi
+            fi
+        done <<< "$branches"
+    fi
+    
+    echo "$highest"
+}
+
+# Function to check existing branches (local and remote) and return next available number
+check_existing_branches() {
+    local specs_dir="$1"
+
+    # Fetch all remotes to get latest branch info (suppress errors if no remotes)
+    git fetch --all --prune 2>/dev/null || true
+
+    # Get highest number from ALL branches (not just matching short name)
+    local highest_branch=$(get_highest_from_branches)
+
+    # Get highest number from ALL specs (not just matching short name)
+    local highest_spec=$(get_highest_from_specs "$specs_dir")
+
+    # Take the maximum of both
+    local max_num=$highest_branch
+    if [ "$highest_spec" -gt "$max_num" ]; then
+        max_num=$highest_spec
+    fi
+
+    # Return next number
+    echo $((max_num + 1))
+}
+
+# Function to clean and format a branch name
+clean_branch_name() {
+    local name="$1"
+    echo "$name" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+# Function to generate branch name with stop word filtering and length filtering
+generate_branch_name() {
+    local description="$1"
+    
+    # Common stop words to filter out
+    local stop_words="^(i|a|an|the|to|for|of|in|on|at|by|with|from|is|are|was|were|be|been|being|have|has|had|do|does|did|will|would|should|could|can|may|might|must|shall|this|that|these|those|my|your|our|their|want|need|add|get|set)$"
+    
+    # Convert to lowercase and split into words
+    local clean_name=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
+    
+    # Filter words: remove stop words and words shorter than 3 chars (unless they're uppercase acronyms in original)
+    local meaningful_words=()
+    for word in $clean_name; do
+        # Skip empty words
+        [ -z "$word" ] && continue
+        
+        # Keep words that are NOT stop words AND (length >= 3 OR are potential acronyms)
+        if ! echo "$word" | grep -qiE "$stop_words"; then
+            if [ ${#word} -ge 3 ]; then
+                meaningful_words+=("$word")
+            elif echo "$description" | grep -q "\b${word^^}\b"; then
+                # Keep short words if they appear as uppercase in original (likely acronyms)
+                meaningful_words+=("$word")
+            fi
+        fi
+    done
+    
+    # If we have meaningful words, use first 3-4 of them
+    if [ ${#meaningful_words[@]} -gt 0 ]; then
+        local max_words=3
+        if [ ${#meaningful_words[@]} -eq 4 ]; then max_words=4; fi
+        
+        local result=""
+        local count=0
+        for word in "${meaningful_words[@]}"; do
+            if [ $count -ge $max_words ]; then break; fi
+            if [ -n "$result" ]; then result="$result-"; fi
+            result="$result$word"
+            count=$((count + 1))
+        done
+        echo "$result"
+    else
+        # Fallback to original logic if no meaningful words found
+        local cleaned=$(clean_branch_name "$description")
+        echo "$cleaned" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//'
+    fi
+}
+
+# Generate branch name
+if [ -n "$SHORT_NAME" ]; then
+    # Use provided short name, just clean it up
+    BRANCH_SUFFIX=$(clean_branch_name "$SHORT_NAME")
+else
+    # Generate from description with smart filtering
+    BRANCH_SUFFIX=$(generate_branch_name "$FEATURE_DESCRIPTION")
+fi
+
+# Determine branch number
+if [ -z "$BRANCH_NUMBER" ]; then
+    if [ "$HAS_GIT" = true ]; then
+        # Check existing branches on remotes
+        BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+    else
+        # Fall back to local directory check
+        HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+        BRANCH_NUMBER=$((HIGHEST + 1))
+    fi
+fi
+
+# Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
+FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
+
+# GitHub enforces a 244-byte limit on branch names
+# Validate and truncate if necessary
+MAX_BRANCH_LENGTH=244
+if [ ${#BRANCH_NAME} -gt $MAX_BRANCH_LENGTH ]; then
+    # Calculate how much we need to trim from suffix
+    # Account for: feature number (3) + hyphen (1) = 4 chars
+    MAX_SUFFIX_LENGTH=$((MAX_BRANCH_LENGTH - 4))
+    
+    # Truncate suffix at word boundary if possible
+    TRUNCATED_SUFFIX=$(echo "$BRANCH_SUFFIX" | cut -c1-$MAX_SUFFIX_LENGTH)
+    # Remove trailing hyphen if truncation created one
+    TRUNCATED_SUFFIX=$(echo "$TRUNCATED_SUFFIX" | sed 's/-$//')
+    
+    ORIGINAL_BRANCH_NAME="$BRANCH_NAME"
+    BRANCH_NAME="${FEATURE_NUM}-${TRUNCATED_SUFFIX}"
+    
+    >&2 echo "[specify] Warning: Branch name exceeded GitHub's 244-byte limit"
+    >&2 echo "[specify] Original: $ORIGINAL_BRANCH_NAME (${#ORIGINAL_BRANCH_NAME} bytes)"
+    >&2 echo "[specify] Truncated to: $BRANCH_NAME (${#BRANCH_NAME} bytes)"
+fi
+
+if [ "$HAS_GIT" = true ]; then
+    git checkout -b "$BRANCH_NAME"
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+
+# Auto-create history/prompts/<branch-name>/ directory (same as specs/<branch-name>/)
+# This keeps naming consistent across branch, specs, and prompts directories
+PROMPTS_DIR="$REPO_ROOT/history/prompts/$BRANCH_NAME"
+mkdir -p "$PROMPTS_DIR"
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi

.specify/scripts/bash/create-phr.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# create-phr.sh - Create Prompt History Record (PHR) - Spec Kit Native
+# 
+# Deterministic PHR location strategy:
+# 1. Constitution stage:
+#    → history/prompts/constitution/
+#    → stage: constitution
+#    → naming: 0001-title.constitution.prompt.md
+#
+# 2. Feature stages (spec-specific work):
+#    → history/prompts/<spec-name>/
+#    → stages: spec, plan, tasks, red, green, refactor, explainer, misc
+#    → naming: 0001-title.spec.prompt.md
+#
+# 3. General stage (catch-all):
+#    → history/prompts/general/
+#    → stage: general
+#    → naming: 0001-title.general.prompt.md
+#
+# This script ONLY:
+#   1. Creates the correct directory structure
+#   2. Copies the template with {{PLACEHOLDERS}} intact
+#   3. Returns metadata (id, path, context) for AI to fill in
+#
+# The calling AI agent is responsible for filling {{PLACEHOLDERS}}
+#
+# Usage:
+#   scripts/bash/create-phr.sh \
+#     --title "Setup authentication" \
+#     --stage architect \
+#     [--feature 001-auth] \
+#     [--json]
+
+JSON_MODE=false
+TITLE=""
+STAGE=""
+FEATURE=""
+
+# Parse arguments
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --json) JSON_MODE=true; shift ;;
+    --title) TITLE=${2:-}; shift 2 ;;
+    --stage) STAGE=${2:-}; shift 2 ;;
+    --feature) FEATURE=${2:-}; shift 2 ;;
+    --help|-h)
+      cat <<EOF
+Usage: $0 --title <title> --stage <stage> [options]
+
+Required:
+  --title <text>       Title for the PHR (used for filename)
+  --stage <stage>      constitution|spec|plan|tasks|red|green|refactor|explainer|misc|general
+
+Optional:
+  --feature <slug>     Feature slug (e.g., 001-auth). Auto-detected from branch if omitted.
+  --json               Output JSON with id, path, and context
+
+Location Rules (all under history/prompts/):
+  - constitution → history/prompts/constitution/
+  - spec, plan, tasks, red, green, refactor, explainer, misc → history/prompts/<branch-name>/
+  - general → history/prompts/general/ (catch-all for non-feature work)
+
+Output:
+  Creates PHR file with template placeholders ({{ID}}, {{TITLE}}, etc.)
+  AI agent must fill these placeholders after creation
+
+Examples:
+  # Early-phase constitution work (no feature exists)
+  $0 --title "Define quality standards" --stage constitution --json
+
+  # Feature-specific implementation work
+  $0 --title "Implement login" --stage green --feature 001-auth --json
+EOF
+      exit 0
+      ;;
+    *) shift ;;
+  esac
+done
+
+# Validation
+if [[ -z "$TITLE" ]]; then
+  echo "Error: --title is required" >&2
+  exit 1
+fi
+
+if [[ -z "$STAGE" ]]; then
+  echo "Error: --stage is required" >&2
+  exit 1
+fi
+
+# Get repository root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
+SPECS_DIR="$REPO_ROOT/specs"
+
+# Check for template (try both locations)
+TEMPLATE_PATH=""
+if [[ -f "$REPO_ROOT/.specify/templates/phr-template.prompt.md" ]]; then
+  TEMPLATE_PATH="$REPO_ROOT/.specify/templates/phr-template.prompt.md"
+elif [[ -f "$REPO_ROOT/templates/phr-template.prompt.md" ]]; then
+  TEMPLATE_PATH="$REPO_ROOT/templates/phr-template.prompt.md"
+else
+  echo "Error: PHR template not found at .specify/templates/ or templates/" >&2
+  exit 1
+fi
+
+# Deterministic location logic based on STAGE
+# New structure: all prompts go under history/prompts/ with subdirectories:
+# - constitution/ for constitution prompts
+# - <spec-name>/ for spec-specific prompts
+# - general/ for general/catch-all prompts
+
+case "$STAGE" in
+  constitution)
+    # Constitution prompts always go to history/prompts/constitution/
+    PROMPTS_DIR="$REPO_ROOT/history/prompts/constitution"
+    VALID_STAGES=("constitution")
+    CONTEXT="constitution"
+    ;;
+  spec|plan|tasks|red|green|refactor|explainer|misc)
+    # Feature-specific stages: require specs/ directory and feature context
+    if [[ ! -d "$SPECS_DIR" ]]; then
+      echo "Error: Feature stage '$STAGE' requires specs/ directory and a feature context" >&2
+      echo "Run /sp.feature first to create a feature, then try again" >&2
+      exit 1
+    fi
+
+    # Auto-detect feature if not specified
+    if [[ -z "$FEATURE" ]]; then
+      # Try to get from SPECIFY_FEATURE environment variable
+      if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        FEATURE="$SPECIFY_FEATURE"
+      # Try to match current branch
+      elif git rev-parse --show-toplevel >/dev/null 2>&1; then
+        BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
+        if [[ -n "$BRANCH" && "$BRANCH" != "main" && "$BRANCH" != "master" ]]; then
+          # Check if branch name matches a feature directory
+          if [[ -d "$SPECS_DIR/$BRANCH" ]]; then
+            FEATURE="$BRANCH"
+          fi
+        fi
+      fi
+
+      # If still no feature, find the highest numbered feature
+      if [[ -z "$FEATURE" ]]; then
+        max_num=0
+        latest_feature=""
+        for dir in "$SPECS_DIR"/*; do
+          if [[ -d "$dir" ]]; then
+            dirname=$(basename "$dir")
+            if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+              num=$((10#${BASH_REMATCH[1]}))
+              if (( num > max_num )); then
+                max_num=$num
+                latest_feature="$dirname"
+              fi
+            fi
+          fi
+        done
+
+        if [[ -n "$latest_feature" ]]; then
+          FEATURE="$latest_feature"
+        else
+          echo "Error: No feature specified and no numbered features found in $SPECS_DIR" >&2
+          echo "Please specify --feature or create a feature directory first" >&2
+          exit 1
+        fi
+      fi
+    fi
+
+    # Validate feature exists
+    if [[ ! -d "$SPECS_DIR/$FEATURE" ]]; then
+      echo "Error: Feature directory not found: $SPECS_DIR/$FEATURE" >&2
+      echo "Available features:" >&2
+      ls -1 "$SPECS_DIR" 2>/dev/null | head -5 | sed 's/^/  - /' >&2
+      exit 1
+    fi
+
+    # Feature prompts go to history/prompts/<branch-name>/ (same as specs/<branch-name>/)
+    # This keeps naming consistent across branch, specs, and prompts directories
+    PROMPTS_DIR="$REPO_ROOT/history/prompts/$FEATURE"
+    VALID_STAGES=("spec" "plan" "tasks" "red" "green" "refactor" "explainer" "misc")
+    CONTEXT="feature"
+    ;;
+  general)
+    # General stage: catch-all that goes to history/prompts/general/
+    PROMPTS_DIR="$REPO_ROOT/history/prompts/general"
+    VALID_STAGES=("general")
+    CONTEXT="general"
+    ;;
+  *)
+    echo "Error: Unknown stage '$STAGE'" >&2
+    exit 1
+    ;;
+esac
+
+# Validate stage
+stage_valid=false
+for valid_stage in "${VALID_STAGES[@]}"; do
+  if [[ "$STAGE" == "$valid_stage" ]]; then
+    stage_valid=true
+    break
+  fi
+done
+
+if [[ "$stage_valid" == "false" ]]; then
+  echo "Error: Invalid stage '$STAGE' for $CONTEXT context" >&2
+  echo "Valid stages for $CONTEXT: ${VALID_STAGES[*]}" >&2
+  exit 1
+fi
+
+# Ensure prompts directory exists
+mkdir -p "$PROMPTS_DIR"
+
+# Helper: slugify
+slugify() {
+  echo "$1" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//'
+}
+
+# Get next ID (local to this directory)
+get_next_id() {
+  local max_id=0
+  for file in "$PROMPTS_DIR"/[0-9][0-9][0-9][0-9]-*.prompt.md; do
+    [[ -e "$file" ]] || continue
+    local base=$(basename "$file")
+    local num=${base%%-*}
+    if [[ "$num" =~ ^[0-9]{4}$ ]]; then
+      local value=$((10#$num))
+      if (( value > max_id )); then
+        max_id=$value
+      fi
+    fi
+  done
+  printf '%04d' $((max_id + 1))
+}
+
+PHR_ID=$(get_next_id)
+TITLE_SLUG=$(slugify "$TITLE")
+STAGE_SLUG=$(slugify "$STAGE")
+
+# Create filename with stage extension
+OUTFILE="$PROMPTS_DIR/${PHR_ID}-${TITLE_SLUG}.${STAGE_SLUG}.prompt.md"
+
+# Simply copy the template (AI will fill placeholders)
+cp "$TEMPLATE_PATH" "$OUTFILE"
+
+# Output results
+ABS_PATH=$(cd "$(dirname "$OUTFILE")" && pwd)/$(basename "$OUTFILE")
+if $JSON_MODE; then
+  printf '{"id":"%s","path":"%s","context":"%s","stage":"%s","feature":"%s","template":"%s"}\n' \
+    "$PHR_ID" "$ABS_PATH" "$CONTEXT" "$STAGE" "${FEATURE:-none}" "$(basename "$TEMPLATE_PATH")"
+else
+  echo "✅ PHR template copied → $ABS_PATH"
+  echo "Note: AI agent should now fill in {{PLACEHOLDERS}}"
+fi

.specify/scripts/bash/setup-plan.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+if [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
+

.specify/scripts/bash/update-agent-context.sh

@@ -0,0 +1,799 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf, Kilo Code, Auggie CLI, Roo Code, CodeBuddy CLI, Qoder CLI, Amp, SHAI, or Amazon Q Developer CLI
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|shai|q|bob|qoder
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(CDPATH="" cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/agents/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+CODEBUDDY_FILE="$REPO_ROOT/CODEBUDDY.md"
+QODER_FILE="$REPO_ROOT/QODER.md"
+AMP_FILE="$REPO_ROOT/AGENTS.md"
+SHAI_FILE="$REPO_ROOT/SHAI.md"
+Q_FILE="$REPO_ROOT/AGENTS.md"
+BOB_FILE="$REPO_ROOT/AGENTS.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test \\&\\& npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+    
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+    
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Check if sections exist in the file
+    local has_active_technologies=0
+    local has_recent_changes=0
+    
+    if grep -q "^## Active Technologies" "$target_file" 2>/dev/null; then
+        has_active_technologies=1
+    fi
+    
+    if grep -q "^## Recent Changes" "$target_file" 2>/dev/null; then
+        has_recent_changes=1
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    local file_ended=false
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    # If sections don't exist, add them at the end of the file
+    if [[ $has_active_technologies -eq 0 ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        echo "" >> "$temp_file"
+        echo "## Active Technologies" >> "$temp_file"
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+        tech_entries_added=true
+    fi
+    
+    if [[ $has_recent_changes -eq 0 ]] && [[ -n "$new_change_entry" ]]; then
+        echo "" >> "$temp_file"
+        echo "## Recent Changes" >> "$temp_file"
+        echo "$new_change_entry" >> "$temp_file"
+        changes_entries_added=true
+    fi
+    
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code"
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI"
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+            ;;
+        cursor-agent)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE"
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code"
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode"
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI"
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf"
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code"
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code"
+            ;;
+        codebuddy)
+            update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+            ;;
+        qoder)
+            update_agent_file "$QODER_FILE" "Qoder CLI"
+            ;;
+        amp)
+            update_agent_file "$AMP_FILE" "Amp"
+            ;;
+        shai)
+            update_agent_file "$SHAI_FILE" "SHAI"
+            ;;
+        q)
+            update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+            ;;
+        bob)
+            update_agent_file "$BOB_FILE" "IBM Bob"
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|roo|amp|shai|q|bob|qoder"
+            exit 1
+            ;;
+    esac
+}
+
+update_all_existing_agents() {
+    local found_agent=false
+    
+    # Check each possible agent file and update if it exists
+    if [[ -f "$CLAUDE_FILE" ]]; then
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$GEMINI_FILE" ]]; then
+        update_agent_file "$GEMINI_FILE" "Gemini CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$COPILOT_FILE" ]]; then
+        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+        found_agent=true
+    fi
+    
+    if [[ -f "$CURSOR_FILE" ]]; then
+        update_agent_file "$CURSOR_FILE" "Cursor IDE"
+        found_agent=true
+    fi
+    
+    if [[ -f "$QWEN_FILE" ]]; then
+        update_agent_file "$QWEN_FILE" "Qwen Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$AGENTS_FILE" ]]; then
+        update_agent_file "$AGENTS_FILE" "Codex/opencode"
+        found_agent=true
+    fi
+    
+    if [[ -f "$WINDSURF_FILE" ]]; then
+        update_agent_file "$WINDSURF_FILE" "Windsurf"
+        found_agent=true
+    fi
+    
+    if [[ -f "$KILOCODE_FILE" ]]; then
+        update_agent_file "$KILOCODE_FILE" "Kilo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$AUGGIE_FILE" ]]; then
+        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$ROO_FILE" ]]; then
+        update_agent_file "$ROO_FILE" "Roo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$CODEBUDDY_FILE" ]]; then
+        update_agent_file "$CODEBUDDY_FILE" "CodeBuddy CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$SHAI_FILE" ]]; then
+        update_agent_file "$SHAI_FILE" "SHAI"
+        found_agent=true
+    fi
+
+    if [[ -f "$QODER_FILE" ]]; then
+        update_agent_file "$QODER_FILE" "Qoder CLI"
+        found_agent=true
+    fi
+
+    if [[ -f "$Q_FILE" ]]; then
+        update_agent_file "$Q_FILE" "Amazon Q Developer CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$BOB_FILE" ]]; then
+        update_agent_file "$BOB_FILE" "IBM Bob"
+        found_agent=true
+    fi
+    
+    # If no agent files exist, create a default Claude file
+    if [[ "$found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+    fi
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+
+    log_info "Usage: $0 [claude|gemini|copilot|cursor-agent|qwen|opencode|codex|windsurf|kilocode|auggie|codebuddy|shai|q|bob|qoder]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
+

.specify/templates/adr-template.md

@@ -0,0 +1,56 @@
+# ADR-{{ID}}: {{TITLE}}
+
+> **Scope**: Document decision clusters, not individual technology choices. Group related decisions that work together (e.g., "Frontend Stack" not separate ADRs for framework, styling, deployment).
+
+- **Status:** Proposed | Accepted | Superseded | Rejected
+- **Date:** {{DATE_ISO}}
+- **Feature:** {{FEATURE_NAME}}
+- **Context:** {{CONTEXT}}
+
+<!-- Significance checklist (ALL must be true to justify this ADR)
+     1) Impact: Long-term consequence for architecture/platform/security?
+     2) Alternatives: Multiple viable options considered with tradeoffs?
+     3) Scope: Cross-cutting concern (not an isolated detail)?
+     If any are false, prefer capturing as a PHR note instead of an ADR. -->
+
+## Decision
+
+{{DECISION}}
+
+<!-- For technology stacks, list all components:
+     - Framework: Next.js 14 (App Router)
+     - Styling: Tailwind CSS v3
+     - Deployment: Vercel
+     - State Management: React Context (start simple)
+-->
+
+## Consequences
+
+### Positive
+
+{{POSITIVE_CONSEQUENCES}}
+
+<!-- Example: Integrated tooling, excellent DX, fast deploys, strong TypeScript support -->
+
+### Negative
+
+{{NEGATIVE_CONSEQUENCES}}
+
+<!-- Example: Vendor lock-in to Vercel, framework coupling, learning curve -->
+
+## Alternatives Considered
+
+{{ALTERNATIVES}}
+
+<!-- Group alternatives by cluster:
+     Alternative Stack A: Remix + styled-components + Cloudflare
+     Alternative Stack B: Vite + vanilla CSS + AWS Amplify
+     Why rejected: Less integrated, more setup complexity
+-->
+
+## References
+
+- Feature Spec: {{SPEC_LINK}}
+- Implementation Plan: {{PLAN_LINK}}
+- Related ADRs: {{RELATED_ADRS}}
+- Evaluator Evidence: {{EVAL_NOTES_LINK}} <!-- link to eval notes/PHR showing graders and outcomes -->

.specify/templates/agent-file-template.md

@@ -0,0 +1,28 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+
+```text
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->

.specify/templates/checklist-template.md

@@ -0,0 +1,40 @@
+# [CHECKLIST TYPE] Checklist: [FEATURE NAME]
+
+**Purpose**: [Brief description of what this checklist covers]
+**Created**: [DATE]
+**Feature**: [Link to spec.md or relevant documentation]
+
+**Note**: This checklist is generated by the `/sp.checklist` command based on feature context and requirements.
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The checklist items below are SAMPLE ITEMS for illustration only.
+  
+  The /sp.checklist command MUST replace these with actual items based on:
+  - User's specific checklist request
+  - Feature requirements from spec.md
+  - Technical context from plan.md
+  - Implementation details from tasks.md
+  
+  DO NOT keep these sample items in the generated checklist file.
+  ============================================================================
+-->
+
+## [Category 1]
+
+- [ ] CHK001 First checklist item with clear action
+- [ ] CHK002 Second checklist item
+- [ ] CHK003 Third checklist item
+
+## [Category 2]
+
+- [ ] CHK004 Another category item
+- [ ] CHK005 Item with specific criteria
+- [ ] CHK006 Final item in this category
+
+## Notes
+
+- Check items off as completed: `[x]`
+- Add comments or findings inline
+- Link to relevant resources or documentation
+- Items are numbered sequentially for easy reference

.specify/templates/phr-template.prompt.md

@@ -0,0 +1,45 @@
+---
+id: {{ID}}
+title: {{TITLE}}
+stage: {{STAGE}}
+date: {{DATE_ISO}}
+surface: {{SURFACE}}
+model: {{MODEL}}
+feature: {{FEATURE}}
+branch: {{BRANCH}}
+user: {{USER}}
+command: {{COMMAND}}
+labels: [{{LABELS}}]
+links:
+  spec: {{LINKS_SPEC}}
+  ticket: {{LINKS_TICKET}}
+  adr: {{LINKS_ADR}}
+  pr: {{LINKS_PR}}
+files:
+{{FILES_YAML}}
+tests:
+{{TESTS_YAML}}
+---
+
+## Prompt
+
+{{PROMPT_TEXT}}
+
+## Response snapshot
+
+{{RESPONSE_TEXT}}
+
+## Outcome
+
+- ✅ Impact: {{OUTCOME_IMPACT}}
+- 🧪 Tests: {{TESTS_SUMMARY}}
+- 📁 Files: {{FILES_SUMMARY}}
+- 🔁 Next prompts: {{NEXT_PROMPTS}}
+- 🧠 Reflection: {{REFLECTION_NOTE}}
+
+## Evaluation notes (flywheel)
+
+- Failure modes observed: {{FAILURE_MODES}}
+- Graders run and results (PASS/FAIL): {{GRADER_RESULTS}}
+- Prompt variant (if applicable): {{PROMPT_VARIANT_ID}}
+- Next experiment (smallest change to try): {{NEXT_EXPERIMENT}}

.specify/templates/plan-template.md

@@ -0,0 +1,104 @@
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+**Note**: This template is filled in by the `/sp.plan` command. See `.specify/templates/commands/plan.md` for the execution workflow.
+
+## Summary
+
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+
+<!--
+  ACTION REQUIRED: Replace the content in this section with the technical details
+  for the project. The structure here is presented in advisory capacity to guide
+  the iteration process.
+-->
+
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+[Gates determined based on constitution file]
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/[###-feature]/
+├── plan.md              # This file (/sp.plan command output)
+├── research.md          # Phase 0 output (/sp.plan command)
+├── data-model.md        # Phase 1 output (/sp.plan command)
+├── quickstart.md        # Phase 1 output (/sp.plan command)
+├── contracts/           # Phase 1 output (/sp.plan command)
+└── tasks.md             # Phase 2 output (/sp.tasks command - NOT created by /sp.plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+
+```text
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Complexity Tracking
+
+> **Fill ONLY if Constitution Check has violations that must be justified**
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |

.specify/templates/spec-template.md

@@ -0,0 +1,115 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## User Scenarios & Testing *(mandatory)*
+
+<!--
+  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
+  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement just ONE of them,
+  you should still have a viable MVP (Minimum Viable Product) that delivers value.
+  
+  Assign priorities (P1, P2, P3, etc.) to each story, where P1 is the most critical.
+  Think of each story as a standalone slice of functionality that can be:
+  - Developed independently
+  - Tested independently
+  - Deployed independently
+  - Demonstrated to users independently
+-->
+
+### User Story 1 - [Brief Title] (Priority: P1)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently - e.g., "Can be fully tested by [specific action] and delivers [specific value]"]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 2 - [Brief Title] (Priority: P2)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+### User Story 3 - [Brief Title] (Priority: P3)
+
+[Describe this user journey in plain language]
+
+**Why this priority**: [Explain the value and why it has this priority level]
+
+**Independent Test**: [Describe how this can be tested independently]
+
+**Acceptance Scenarios**:
+
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+---
+
+[Add more user stories as needed, each with an assigned priority]
+
+### Edge Cases
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right edge cases.
+-->
+
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+<!--
+  ACTION REQUIRED: The content in this section represents placeholders.
+  Fill them out with the right functional requirements.
+-->
+
+### Functional Requirements
+
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+## Success Criteria *(mandatory)*
+
+<!--
+  ACTION REQUIRED: Define measurable success criteria.
+  These must be technology-agnostic and measurable.
+-->
+
+### Measurable Outcomes
+
+- **SC-001**: [Measurable metric, e.g., "Users can complete account creation in under 2 minutes"]
+- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users without degradation"]
+- **SC-003**: [User satisfaction metric, e.g., "90% of users successfully complete primary task on first attempt"]
+- **SC-004**: [Business metric, e.g., "Reduce support tickets related to [X] by 50%"]

.specify/templates/tasks-template.md

@@ -0,0 +1,251 @@
+---
+
+description: "Task list template for feature implementation"
+---
+
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/
+
+**Tests**: The examples below include test tasks. Tests are OPTIONAL - only include them if explicitly requested in the feature specification.
+
+**Organization**: Tasks are grouped by user story to enable independent implementation and testing of each story.
+
+## Format: `[ID] [P?] [Story] Description`
+
+- **[P]**: Can run in parallel (different files, no dependencies)
+- **[Story]**: Which user story this task belongs to (e.g., US1, US2, US3)
+- Include exact file paths in descriptions
+
+## Path Conventions
+
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+<!-- 
+  ============================================================================
+  IMPORTANT: The tasks below are SAMPLE TASKS for illustration purposes only.
+  
+  The /sp.tasks command MUST replace these with actual tasks based on:
+  - User stories from spec.md (with their priorities P1, P2, P3...)
+  - Feature requirements from plan.md
+  - Entities from data-model.md
+  - Endpoints from contracts/
+  
+  Tasks MUST be organized by user story so each story can be:
+  - Implemented independently
+  - Tested independently
+  - Delivered as an MVP increment
+  
+  DO NOT keep these sample tasks in the generated tasks.md file.
+  ============================================================================
+-->
+
+## Phase 1: Setup (Shared Infrastructure)
+
+**Purpose**: Project initialization and basic structure
+
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+---
+
+## Phase 2: Foundational (Blocking Prerequisites)
+
+**Purpose**: Core infrastructure that MUST be complete before ANY user story can be implemented
+
+**⚠️ CRITICAL**: No user story work can begin until this phase is complete
+
+Examples of foundational tasks (adjust based on your project):
+
+- [ ] T004 Setup database schema and migrations framework
+- [ ] T005 [P] Implement authentication/authorization framework
+- [ ] T006 [P] Setup API routing and middleware structure
+- [ ] T007 Create base models/entities that all stories depend on
+- [ ] T008 Configure error handling and logging infrastructure
+- [ ] T009 Setup environment configuration management
+
+**Checkpoint**: Foundation ready - user story implementation can now begin in parallel
+
+---
+
+## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 1 (OPTIONAL - only if tests requested) ⚠️
+
+> **NOTE: Write these tests FIRST, ensure they FAIL before implementation**
+
+- [ ] T010 [P] [US1] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T011 [P] [US1] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 1
+
+- [ ] T012 [P] [US1] Create [Entity1] model in src/models/[entity1].py
+- [ ] T013 [P] [US1] Create [Entity2] model in src/models/[entity2].py
+- [ ] T014 [US1] Implement [Service] in src/services/[service].py (depends on T012, T013)
+- [ ] T015 [US1] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T016 [US1] Add validation and error handling
+- [ ] T017 [US1] Add logging for user story 1 operations
+
+**Checkpoint**: At this point, User Story 1 should be fully functional and testable independently
+
+---
+
+## Phase 4: User Story 2 - [Title] (Priority: P2)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 2 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T018 [P] [US2] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T019 [P] [US2] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 2
+
+- [ ] T020 [P] [US2] Create [Entity] model in src/models/[entity].py
+- [ ] T021 [US2] Implement [Service] in src/services/[service].py
+- [ ] T022 [US2] Implement [endpoint/feature] in src/[location]/[file].py
+- [ ] T023 [US2] Integrate with User Story 1 components (if needed)
+
+**Checkpoint**: At this point, User Stories 1 AND 2 should both work independently
+
+---
+
+## Phase 5: User Story 3 - [Title] (Priority: P3)
+
+**Goal**: [Brief description of what this story delivers]
+
+**Independent Test**: [How to verify this story works on its own]
+
+### Tests for User Story 3 (OPTIONAL - only if tests requested) ⚠️
+
+- [ ] T024 [P] [US3] Contract test for [endpoint] in tests/contract/test_[name].py
+- [ ] T025 [P] [US3] Integration test for [user journey] in tests/integration/test_[name].py
+
+### Implementation for User Story 3
+
+- [ ] T026 [P] [US3] Create [Entity] model in src/models/[entity].py
+- [ ] T027 [US3] Implement [Service] in src/services/[service].py
+- [ ] T028 [US3] Implement [endpoint/feature] in src/[location]/[file].py
+
+**Checkpoint**: All user stories should now be independently functional
+
+---
+
+[Add more user story phases as needed, following the same pattern]
+
+---
+
+## Phase N: Polish & Cross-Cutting Concerns
+
+**Purpose**: Improvements that affect multiple user stories
+
+- [ ] TXXX [P] Documentation updates in docs/
+- [ ] TXXX Code cleanup and refactoring
+- [ ] TXXX Performance optimization across all stories
+- [ ] TXXX [P] Additional unit tests (if requested) in tests/unit/
+- [ ] TXXX Security hardening
+- [ ] TXXX Run quickstart.md validation
+
+---
+
+## Dependencies & Execution Order
+
+### Phase Dependencies
+
+- **Setup (Phase 1)**: No dependencies - can start immediately
+- **Foundational (Phase 2)**: Depends on Setup completion - BLOCKS all user stories
+- **User Stories (Phase 3+)**: All depend on Foundational phase completion
+  - User stories can then proceed in parallel (if staffed)
+  - Or sequentially in priority order (P1 → P2 → P3)
+- **Polish (Final Phase)**: Depends on all desired user stories being complete
+
+### User Story Dependencies
+
+- **User Story 1 (P1)**: Can start after Foundational (Phase 2) - No dependencies on other stories
+- **User Story 2 (P2)**: Can start after Foundational (Phase 2) - May integrate with US1 but should be independently testable
+- **User Story 3 (P3)**: Can start after Foundational (Phase 2) - May integrate with US1/US2 but should be independently testable
+
+### Within Each User Story
+
+- Tests (if included) MUST be written and FAIL before implementation
+- Models before services
+- Services before endpoints
+- Core implementation before integration
+- Story complete before moving to next priority
+
+### Parallel Opportunities
+
+- All Setup tasks marked [P] can run in parallel
+- All Foundational tasks marked [P] can run in parallel (within Phase 2)
+- Once Foundational phase completes, all user stories can start in parallel (if team capacity allows)
+- All tests for a user story marked [P] can run in parallel
+- Models within a story marked [P] can run in parallel
+- Different user stories can be worked on in parallel by different team members
+
+---
+
+## Parallel Example: User Story 1
+
+```bash
+# Launch all tests for User Story 1 together (if tests requested):
+Task: "Contract test for [endpoint] in tests/contract/test_[name].py"
+Task: "Integration test for [user journey] in tests/integration/test_[name].py"
+
+# Launch all models for User Story 1 together:
+Task: "Create [Entity1] model in src/models/[entity1].py"
+Task: "Create [Entity2] model in src/models/[entity2].py"
+```
+
+---
+
+## Implementation Strategy
+
+### MVP First (User Story 1 Only)
+
+1. Complete Phase 1: Setup
+2. Complete Phase 2: Foundational (CRITICAL - blocks all stories)
+3. Complete Phase 3: User Story 1
+4. **STOP and VALIDATE**: Test User Story 1 independently
+5. Deploy/demo if ready
+
+### Incremental Delivery
+
+1. Complete Setup + Foundational → Foundation ready
+2. Add User Story 1 → Test independently → Deploy/Demo (MVP!)
+3. Add User Story 2 → Test independently → Deploy/Demo
+4. Add User Story 3 → Test independently → Deploy/Demo
+5. Each story adds value without breaking previous stories
+
+### Parallel Team Strategy
+
+With multiple developers:
+
+1. Team completes Setup + Foundational together
+2. Once Foundational is done:
+   - Developer A: User Story 1
+   - Developer B: User Story 2
+   - Developer C: User Story 3
+3. Stories complete and integrate independently
+
+---
+
+## Notes
+
+- [P] tasks = different files, no dependencies
+- [Story] label maps task to specific user story for traceability
+- Each user story should be independently completable and testable
+- Verify tests fail before implementing
+- Commit after each task or logical group
+- Stop at any checkpoint to validate story independently
+- Avoid: vague tasks, same file conflicts, cross-story dependencies that break independence

CLAUDE.md

@@ -0,0 +1,210 @@
+# Claude Code Rules
+
+This file is generated during init for the selected agent.
+
+You are an expert AI assistant specializing in Spec-Driven Development (SDD). Your primary goal is to work with the architext to build products.
+
+## Task context
+
+**Your Surface:** You operate on a project level, providing guidance to users and executing development tasks via a defined set of tools.
+
+**Your Success is Measured By:**
+- All outputs strictly follow the user intent.
+- Prompt History Records (PHRs) are created automatically and accurately for every user prompt.
+- Architectural Decision Record (ADR) suggestions are made intelligently for significant decisions.
+- All changes are small, testable, and reference code precisely.
+
+## Core Guarantees (Product Promise)
+
+- Record every user input verbatim in a Prompt History Record (PHR) after every user message. Do not truncate; preserve full multiline input.
+- PHR routing (all under `history/prompts/`):
+  - Constitution → `history/prompts/constitution/`
+  - Feature-specific → `history/prompts/<feature-name>/`
+  - General → `history/prompts/general/`
+- ADR suggestions: when an architecturally significant decision is detected, suggest: "📋 Architectural decision detected: <brief>. Document? Run `/sp.adr <title>`." Never auto‑create ADRs; require user consent.
+
+## Development Guidelines
+
+### 1. Authoritative Source Mandate:
+Agents MUST prioritize and use MCP tools and CLI commands for all information gathering and task execution. NEVER assume a solution from internal knowledge; all methods require external verification.
+
+### 2. Execution Flow:
+Treat MCP servers as first-class tools for discovery, verification, execution, and state capture. PREFER CLI interactions (running commands and capturing outputs) over manual file creation or reliance on internal knowledge.
+
+### 3. Knowledge capture (PHR) for Every User Input.
+After completing requests, you **MUST** create a PHR (Prompt History Record).
+
+**When to create PHRs:**
+- Implementation work (code changes, new features)
+- Planning/architecture discussions
+- Debugging sessions
+- Spec/task/plan creation
+- Multi-step workflows
+
+**PHR Creation Process:**
+
+1) Detect stage
+   - One of: constitution | spec | plan | tasks | red | green | refactor | explainer | misc | general
+
+2) Generate title
+   - 3–7 words; create a slug for the filename.
+
+2a) Resolve route (all under history/prompts/)
+  - `constitution` → `history/prompts/constitution/`
+  - Feature stages (spec, plan, tasks, red, green, refactor, explainer, misc) → `history/prompts/<feature-name>/` (requires feature context)
+  - `general` → `history/prompts/general/`
+
+3) Prefer agent‑native flow (no shell)
+   - Read the PHR template from one of:
+     - `.specify/templates/phr-template.prompt.md`
+     - `templates/phr-template.prompt.md`
+   - Allocate an ID (increment; on collision, increment again).
+   - Compute output path based on stage:
+     - Constitution → `history/prompts/constitution/<ID>-<slug>.constitution.prompt.md`
+     - Feature → `history/prompts/<feature-name>/<ID>-<slug>.<stage>.prompt.md`
+     - General → `history/prompts/general/<ID>-<slug>.general.prompt.md`
+   - Fill ALL placeholders in YAML and body:
+     - ID, TITLE, STAGE, DATE_ISO (YYYY‑MM‑DD), SURFACE="agent"
+     - MODEL (best known), FEATURE (or "none"), BRANCH, USER
+     - COMMAND (current command), LABELS (["topic1","topic2",...])
+     - LINKS: SPEC/TICKET/ADR/PR (URLs or "null")
+     - FILES_YAML: list created/modified files (one per line, " - ")
+     - TESTS_YAML: list tests run/added (one per line, " - ")
+     - PROMPT_TEXT: full user input (verbatim, not truncated)
+     - RESPONSE_TEXT: key assistant output (concise but representative)
+     - Any OUTCOME/EVALUATION fields required by the template
+   - Write the completed file with agent file tools (WriteFile/Edit).
+   - Confirm absolute path in output.
+
+4) Use sp.phr command file if present
+   - If `.**/commands/sp.phr.*` exists, follow its structure.
+   - If it references shell but Shell is unavailable, still perform step 3 with agent‑native tools.
+
+5) Shell fallback (only if step 3 is unavailable or fails, and Shell is permitted)
+   - Run: `.specify/scripts/bash/create-phr.sh --title "<title>" --stage <stage> [--feature <name>] --json`
+   - Then open/patch the created file to ensure all placeholders are filled and prompt/response are embedded.
+
+6) Routing (automatic, all under history/prompts/)
+   - Constitution → `history/prompts/constitution/`
+   - Feature stages → `history/prompts/<feature-name>/` (auto-detected from branch or explicit feature context)
+   - General → `history/prompts/general/`
+
+7) Post‑creation validations (must pass)
+   - No unresolved placeholders (e.g., `{{THIS}}`, `[THAT]`).
+   - Title, stage, and dates match front‑matter.
+   - PROMPT_TEXT is complete (not truncated).
+   - File exists at the expected path and is readable.
+   - Path matches route.
+
+8) Report
+   - Print: ID, path, stage, title.
+   - On any failure: warn but do not block the main command.
+   - Skip PHR only for `/sp.phr` itself.
+
+### 4. Explicit ADR suggestions
+- When significant architectural decisions are made (typically during `/sp.plan` and sometimes `/sp.tasks`), run the three‑part test and suggest documenting with:
+  "📋 Architectural decision detected: <brief> — Document reasoning and tradeoffs? Run `/sp.adr <decision-title>`"
+- Wait for user consent; never auto‑create the ADR.
+
+### 5. Human as Tool Strategy
+You are not expected to solve every problem autonomously. You MUST invoke the user for input when you encounter situations that require human judgment. Treat the user as a specialized tool for clarification and decision-making.
+
+**Invocation Triggers:**
+1.  **Ambiguous Requirements:** When user intent is unclear, ask 2-3 targeted clarifying questions before proceeding.
+2.  **Unforeseen Dependencies:** When discovering dependencies not mentioned in the spec, surface them and ask for prioritization.
+3.  **Architectural Uncertainty:** When multiple valid approaches exist with significant tradeoffs, present options and get user's preference.
+4.  **Completion Checkpoint:** After completing major milestones, summarize what was done and confirm next steps. 
+
+## Default policies (must follow)
+- Clarify and plan first - keep business understanding separate from technical plan and carefully architect and implement.
+- Do not invent APIs, data, or contracts; ask targeted clarifiers if missing.
+- Never hardcode secrets or tokens; use `.env` and docs.
+- Prefer the smallest viable diff; do not refactor unrelated code.
+- Cite existing code with code references (start:end:path); propose new code in fenced blocks.
+- Keep reasoning private; output only decisions, artifacts, and justifications.
+
+### Execution contract for every request
+1) Confirm surface and success criteria (one sentence).
+2) List constraints, invariants, non‑goals.
+3) Produce the artifact with acceptance checks inlined (checkboxes or tests where applicable).
+4) Add follow‑ups and risks (max 3 bullets).
+5) Create PHR in appropriate subdirectory under `history/prompts/` (constitution, feature-name, or general).
+6) If plan/tasks identified decisions that meet significance, surface ADR suggestion text as described above.
+
+### Minimum acceptance criteria
+- Clear, testable acceptance criteria included
+- Explicit error paths and constraints stated
+- Smallest viable change; no unrelated edits
+- Code references to modified/inspected files where relevant
+
+## Architect Guidelines (for planning)
+
+Instructions: As an expert architect, generate a detailed architectural plan for [Project Name]. Address each of the following thoroughly.
+
+1. Scope and Dependencies:
+   - In Scope: boundaries and key features.
+   - Out of Scope: explicitly excluded items.
+   - External Dependencies: systems/services/teams and ownership.
+
+2. Key Decisions and Rationale:
+   - Options Considered, Trade-offs, Rationale.
+   - Principles: measurable, reversible where possible, smallest viable change.
+
+3. Interfaces and API Contracts:
+   - Public APIs: Inputs, Outputs, Errors.
+   - Versioning Strategy.
+   - Idempotency, Timeouts, Retries.
+   - Error Taxonomy with status codes.
+
+4. Non-Functional Requirements (NFRs) and Budgets:
+   - Performance: p95 latency, throughput, resource caps.
+   - Reliability: SLOs, error budgets, degradation strategy.
+   - Security: AuthN/AuthZ, data handling, secrets, auditing.
+   - Cost: unit economics.
+
+5. Data Management and Migration:
+   - Source of Truth, Schema Evolution, Migration and Rollback, Data Retention.
+
+6. Operational Readiness:
+   - Observability: logs, metrics, traces.
+   - Alerting: thresholds and on-call owners.
+   - Runbooks for common tasks.
+   - Deployment and Rollback strategies.
+   - Feature Flags and compatibility.
+
+7. Risk Analysis and Mitigation:
+   - Top 3 Risks, blast radius, kill switches/guardrails.
+
+8. Evaluation and Validation:
+   - Definition of Done (tests, scans).
+   - Output Validation for format/requirements/safety.
+
+9. Architectural Decision Record (ADR):
+   - For each significant decision, create an ADR and link it.
+
+### Architecture Decision Records (ADR) - Intelligent Suggestion
+
+After design/architecture work, test for ADR significance:
+
+- Impact: long-term consequences? (e.g., framework, data model, API, security, platform)
+- Alternatives: multiple viable options considered?
+- Scope: cross‑cutting and influences system design?
+
+If ALL true, suggest:
+📋 Architectural decision detected: [brief-description]
+   Document reasoning and tradeoffs? Run `/sp.adr [decision-title]`
+
+Wait for consent; never auto-create ADRs. Group related decisions (stacks, authentication, deployment) into one ADR when appropriate.
+
+## Basic Project Structure
+
+- `.specify/memory/constitution.md` — Project principles
+- `specs/<feature>/spec.md` — Feature requirements
+- `specs/<feature>/plan.md` — Architecture decisions
+- `specs/<feature>/tasks.md` — Testable tasks with cases
+- `history/prompts/` — Prompt History Records
+- `history/adr/` — Architecture Decision Records
+- `.specify/` — SpecKit Plus templates and scripts
+
+## Code Standards
+See `.specify/memory/constitution.md` for code quality, testing, performance, security, and architecture principles.

Dockerfile

@@ -0,0 +1,56 @@
+# ============================================================================
+# HuggingFace Spaces — FastAPI backend (8000) + Next.js standalone (7860)
+# Frontend built inside Docker so source changes always deploy correctly
+# ============================================================================
+FROM python:3.11-slim
+
+# Install Node.js 18 + supervisor
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        curl ca-certificates xz-utils supervisor \
+    && curl -fsSL "https://nodejs.org/dist/v18.20.4/node-v18.20.4-linux-x64.tar.xz" \
+       | tar -xJ -C /usr/local --strip-components=1 \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# ── Python backend ──────────────────────────────────────────────────────────
+COPY phase-1-core-infra/backend/requirements.txt ./
+RUN pip install --no-cache-dir --upgrade pip \
+    && pip install --no-cache-dir -r requirements.txt
+
+COPY phase-1-core-infra/backend/ ./backend/
+
+# ── Next.js frontend — build from source ───────────────────────────────────
+COPY phase-1-core-infra/frontend/package.json phase-1-core-infra/frontend/package-lock.json /build/frontend/
+RUN cd /build/frontend && npm ci --legacy-peer-deps
+
+COPY phase-1-core-infra/frontend/ /build/frontend/
+RUN cd /build/frontend \
+    && NEXT_PUBLIC_API_URL=http://localhost:8000 \
+       NEXT_TELEMETRY_DISABLED=1 \
+       npm run build
+
+# Copy standalone output into /app/frontend
+RUN cp -r /build/frontend/.next/standalone/. /app/frontend/ \
+    && cp -r /build/frontend/.next/static/. /app/frontend/.next/static/ \
+    && rm -rf /build
+
+# ── Runtime setup ───────────────────────────────────────────────────────────
+RUN mkdir -p /var/log/supervisor /app/backend/uploads
+COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
+RUN useradd -m -u 1000 appuser \
+    && chown -R appuser:appuser /app /var/log/supervisor
+
+EXPOSE 7860
+
+ENV PYTHONUNBUFFERED=1 \
+    NODE_ENV=production \
+    PORT=7860 \
+    HOSTNAME=0.0.0.0 \
+    NEXT_PUBLIC_API_URL=http://localhost:8000 \
+    NEXT_TELEMETRY_DISABLED=1
+
+HEALTHCHECK --interval=30s --timeout=15s --start-period=120s --retries=3 \
+    CMD curl -f http://localhost:7860 || exit 1
+
+CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/conf.d/supervisord.conf"]

README.md

@@ -0,0 +1,310 @@
+---
+title: AI Marketing Automation
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
+sdk: docker
+sdk_version: latest
+app_port: 7860
+pinned: false
+license: mit
+---
+
+# 🤖 Autonomous AI Marketing Agency
+
+**Multi-tenant AI-powered marketing automation platform** with intelligent content generation, video creation, and WhatsApp approval workflows.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![Next.js 14](https://img.shields.io/badge/Next.js-14-black)](https://nextjs.org/)
+
+---
+
+## ✨ Features
+
+### 🎨 AI Content Generation
+- Multi-platform content creation using **Claude** and **GPT-4**
+- Platform-specific optimization (LinkedIn, X/Twitter, Instagram, Facebook)
+- Quality-based refinement loop with AI critic agent
+- DALL-E 3 image generation with multiple aspect ratios
+- Voice-to-text with OpenAI Whisper
+
+### 🎥 Video Generation
+- Automated video creation with **Google Veo**
+- Text-to-speech integration
+- Cinematic prompt generation
+- Multiple style and mood options
+- Video library management
+
+### 💬 WhatsApp Approval Workflow
+- Human-in-the-loop content approval via WhatsApp
+- Command-based interface (YES/NO/EDIT)
+- 24-hour approval timeout with reminders
+- Multi-platform publishing after approval
+- Complete audit trail
+
+### 📊 Self-Learning Analytics
+- Real-time engagement tracking across all platforms
+- AI-powered pattern recognition
+- Statistical trend analysis
+- Automatic prompt enhancement based on performance
+- Insights dashboard with interactive charts
+
+### 💳 SaaS Multi-Tenancy
+- Stripe-powered subscription management
+- Tiered pricing (Basic, Pro, Agency)
+- Usage tracking and limit enforcement
+- Row-level security for data isolation
+- Admin dashboard for user management
+
+### 🔐 Security & Authentication
+- **Better Auth** - Self-hosted authentication system
+  - Email/password authentication with strong password requirements
+  - OAuth social login (Google, GitHub)
+  - Password reset and email verification
+  - Session management with JWT tokens
+  - Admin role management
+- AES-256 encryption for API tokens
+- Rate limiting on all endpoints
+- CSRF protection with state parameters
+
+---
+
+## 🏗️ Architecture
+
+### Technology Stack
+
+**Frontend**
+- Next.js 14 (App Router)
+- TypeScript
+- Tailwind CSS
+- React Query
+- Recharts
+
+**Backend**
+- FastAPI (Python 3.11+)
+- SQLAlchemy (async)
+- Alembic (migrations)
+- Celery (background jobs)
+- APScheduler (scheduled tasks)
+
+**AI & ML**
+- OpenAI GPT-4 & DALL-E 3
+- Anthropic Claude
+- Google Veo (video generation)
+- Google Cloud TTS
+
+**Infrastructure**
+- PostgreSQL (Neon/Supabase)
+- Redis (caching & sessions)
+- Docker & Docker Compose
+- HuggingFace Spaces (deployment)
+
+### Phase Architecture
+
+The platform is organized into 6 independent phases:
+
+1. **Phase 1: Core Infrastructure** - Authentication, user management, OAuth
+2. **Phase 2: AI Content Engine** - Multi-agent content generation
+3. **Phase 3: WhatsApp Approval** - Human-in-the-loop workflow
+4. **Phase 4: Learning Loop** - Analytics and self-improvement
+5. **Phase 5: Video Engine** - Automated video generation
+6. **Phase 6: SaaS Core** - Multi-tenancy and subscriptions
+
+---
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- **Docker & Docker Compose** (recommended) OR
+- **Python 3.11+** and **Node.js 18+** for local development
+- **PostgreSQL Database** (Neon or Supabase recommended)
+- **Redis** (Upstash recommended)
+
+### Option 1: Docker Deployment (Recommended)
+
+```bash
+# 1. Clone repository
+git clone <repository-url>
+cd autonomous-ai-marketing-agency
+
+# 2. Configure environment
+cp .env.example .env
+# Edit .env with your API keys and database URLs
+
+# 3. Start all services
+docker-compose up -d
+
+# 4. Run database migrations
+docker-compose exec backend alembic upgrade head
+
+# 5. Access application
+# Frontend: http://localhost:3000
+# Backend API: http://localhost:8000
+# API Docs: http://localhost:8000/docs
+```
+
+### Option 2: Local Development
+
+```bash
+# 1. Clone repository
+git clone <repository-url>
+cd autonomous-ai-marketing-agency
+
+# 2. Configure environment
+cp .env.example .env
+# Edit .env with your configuration
+
+# 3. Install backend dependencies
+cd phase-1-core-infra/backend
+pip install -r requirements.txt
+
+# 4. Run migrations
+alembic upgrade head
+
+# 5. Start backend (Terminal 1)
+uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+
+# 6. Install frontend dependencies (Terminal 2)
+cd ../frontend
+npm install
+
+# 7. Start frontend
+npm run dev
+
+# 8. Access application
+# Frontend: http://localhost:3000
+# Backend API: http://localhost:8000
+```
+
+### Required Environment Variables
+
+**Minimum Configuration**:
+- `DATABASE_URL` - PostgreSQL connection string (see [Database Setup](docs/database-setup.md))
+- `REDIS_URL` - Redis connection string
+- `BETTER_AUTH_SECRET` - Generate with: `openssl rand -base64 32`
+- `ENCRYPTION_KEY` - Generate with: `python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"`
+- `JWT_SECRET` - Generate with: `openssl rand -hex 32`
+- `OPENAI_API_KEY` - From [OpenAI Platform](https://platform.openai.com)
+- `ANTHROPIC_API_KEY` - From [Anthropic Console](https://console.anthropic.com)
+
+**Optional (for full features)**:
+- `STRIPE_SECRET_KEY` - For subscription management
+- `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` - For Google OAuth
+- `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` - For GitHub OAuth
+- `WHATSAPP_API_TOKEN` - For WhatsApp approval workflow
+- `VEO_API_KEY` - For video generation
+
+See [Environment Variables Guide](docs/environment-variables.md) for complete configuration.
+
+---
+
+## 📚 Documentation
+
+### Getting Started
+- [Database Setup Guide](docs/database-setup.md) - PostgreSQL setup with Neon/Supabase
+- [Environment Variables Guide](docs/environment-variables.md) - Complete configuration reference
+- [Deployment Guide](docs/deployment.md) - Local, Docker, and HuggingFace Spaces deployment
+- [Architecture Overview](docs/architecture.md) - System design and data flow
+
+### Operations
+- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions
+- [Migration Guide](docs/database-setup.md#running-migrations) - Database migration instructions
+
+### Phase Documentation
+- [Phase 1: Core Infrastructure](phase-1-core-infra/README.md) - Authentication and user management
+- [Phase 2: AI Engine](phase-2-ai-engine/README.md) - Content generation
+- [Phase 3: Approval System](phase-3-approval-system/README.md) - WhatsApp workflow
+- [Phase 4: Learning Loop](phase-4-learning-loop/README.md) - Analytics and insights
+
+---
+
+## 🎯 Project Status
+
+**Overall Completion**: ~58% → Target: 95%
+
+- ✅ **Phase 1-3**: Production-ready (100%)
+- ⚠️ **Phase 4**: Functionally complete (78%)
+- 🔄 **Phase 5**: In progress (37% → 90%)
+- 🔄 **Phase 6**: In progress (35% → 90%)
+- ✅ **Better Auth Migration**: Complete (Phases 5-9)
+  - OAuth social login (Google, GitHub)
+  - Password reset with email
+  - Email verification
+  - Admin role management
+  - Comprehensive documentation
+
+See [PROJECT_STATUS_REPORT.md](PROJECT_STATUS_REPORT.md) for detailed status.
+
+---
+
+## 🧪 Testing
+
+```bash
+# Run unit tests
+cd phase-1-core-infra/backend
+pytest
+
+# Run with coverage
+pytest --cov=src --cov-report=html
+
+# Run E2E tests
+cd ../frontend
+npx playwright test
+```
+
+See [TESTING_GUIDE.md](TESTING_GUIDE.md) for comprehensive testing documentation.
+
+---
+
+## 🔒 Security
+
+- **Encryption**: AES-256 for social media tokens, bcrypt for passwords
+- **Authentication**: JWT-based with refresh tokens, OAuth 2.0 support
+- **Authorization**: Role-based access control (RBAC)
+- **Data Isolation**: Row-level security (RLS) for multi-tenancy
+- **Rate Limiting**: 100 requests/minute per user
+- **CSRF Protection**: Enabled on all state-changing operations
+- **Input Validation**: Pydantic schemas for all API inputs
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Please read our contributing guidelines before submitting PRs.
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+---
+
+## 📄 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with [Claude Code](https://claude.ai/code)
+- Powered by [Anthropic Claude](https://www.anthropic.com/)
+- Deployed on [HuggingFace Spaces](https://huggingface.co/spaces)
+
+---
+
+## 📞 Support
+
+- **Documentation**: See `docs/` directory
+- **Issues**: Open an issue on GitHub
+- **Questions**: Check [Troubleshooting Guide](docs/troubleshooting.md)
+
+---
+
+**Last Updated**: 2026-02-12 | **Version**: 1.0.0-beta
+
+Built with ❤️ using AI-powered development
+# Autonomous_AI_Marketing_Agency

phase-1-core-infra/backend/.env.example

@@ -0,0 +1,33 @@
+# =============================================================================
+# Backend Environment Variables
+# =============================================================================
+# Copy this file to .env and fill in your actual values
+# NEVER commit .env to version control
+
+# Database (Neon PostgreSQL)
+# Get your connection string from: https://console.neon.tech/
+# Format: postgresql://user:password@ep-xxx.region.aws.neon.tech/dbname?sslmode=require
+DATABASE_URL=postgresql://user:password@ep-xxx.us-east-2.aws.neon.tech/phase1_dev?sslmode=require
+
+# Encryption
+# Generate with: python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
+ENCRYPTION_KEY=your-fernet-encryption-key-here
+
+# JWT Configuration
+# Generate with: openssl rand -base64 32
+JWT_SECRET=your-jwt-secret-here
+JWT_ALGORITHM=HS256
+JWT_EXPIRATION_DAYS=30
+
+# Backend Configuration
+BACKEND_HOST=0.0.0.0
+BACKEND_PORT=8000
+BACKEND_RELOAD=true
+
+# Environment
+ENVIRONMENT=development
+DEBUG=true
+LOG_LEVEL=INFO
+
+# CORS Configuration
+CORS_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

phase-1-core-infra/backend/.flake8

@@ -0,0 +1,4 @@
+[flake8]
+max-line-length = 100
+exclude = .git,__pycache__,venv,.venv,alembic/versions
+ignore = E203, W503

phase-1-core-infra/backend/alembic.ini

@@ -0,0 +1,105 @@
+# A generic, single database configuration.
+
+[alembic]
+# path to migration scripts
+script_location = alembic
+
+# template used to generate migration files
+file_template = %%(year)d%%(month).2d%%(day).2d_%%(hour).2d%%(minute).2d_%%(rev)s_%%(slug)s
+
+# sys.path path, will be prepended to sys.path if present.
+prepend_sys_path = .
+
+# timezone to use when rendering the date within the migration file
+# as well as the filename.
+# If specified, requires the python-dateutil library that can be
+# installed by adding `alembic[tz]` to the pip requirements
+# string value is passed to dateutil.tz.gettz()
+# leave blank for localtime
+# timezone =
+
+# max length of characters to apply to the
+# "slug" field
+# truncate_slug_length = 40
+
+# set to 'true' to run the environment during
+# the 'revision' command, regardless of autogenerate
+# revision_environment = false
+
+# set to 'true' to allow .pyc and .pyo files without
+# a source .py file to be detected as revisions in the
+# versions/ directory
+# sourceless = false
+
+# version location specification; This defaults
+# to alembic/versions.  When using multiple version
+# directories, initial revisions must be specified with --version-path.
+# The path separator used here should be the separator specified by "version_path_separator" below.
+# version_locations = %(here)s/bar:%(here)s/bat:alembic/versions
+
+# version path separator; As mentioned above, this is the character used to split
+# version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+# If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+# Valid values for version_path_separator are:
+#
+# version_path_separator = :
+# version_path_separator = ;
+# version_path_separator = space
+version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
+
+# the output encoding used when revision files
+# are written from script.py.mako
+# output_encoding = utf-8
+
+# sqlalchemy.url is loaded from environment variables in env.py
+# Do not set it here to avoid conflicts
+# sqlalchemy.url = 
+# If you need to set it here, uncomment and use the NeonDB URL:
+# sqlalchemy.url = postgresql://neondb_owner:npg_52aqEhMxcFpS@ep-falling-sky-ai3kxfa4-pooler.c-4.us-east-1.aws.neon.tech/neondb?sslmode=require&channel_binding=require
+
+
+[post_write_hooks]
+# post_write_hooks defines scripts or Python functions that are run
+# on newly generated revision scripts.  See the documentation for further
+# detail and examples
+
+# format using "black" - use the console_scripts runner, against the "black" entrypoint
+# hooks = black
+# black.type = console_scripts
+# black.entrypoint = black
+# black.options = -l 79 REVISION_SCRIPT_FILENAME
+
+# Logging configuration
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

phase-1-core-infra/backend/alembic/env.py

@@ -0,0 +1,93 @@
+import sys
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+from alembic import context
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+
+# Only load environment variables from .env files if DATABASE_URL is not already set
+# This ensures Docker environment variables take precedence over .env files
+if not os.getenv("DATABASE_URL"):
+    # Explicitly load environment variables from the backend directory first
+    # __file__ is the path to this env.py file in the alembic directory
+    # So we need to go up one level to get to the backend directory
+    backend_dir = Path(__file__).parent  # This is the alembic directory
+    backend_dir = backend_dir.parent    # This is the backend directory
+    backend_env = backend_dir / ".env"
+
+    # Load the backend .env file explicitly
+    if backend_env.exists():
+        print(f"Loading environment from: {backend_env}")
+        load_dotenv(backend_env, override=True)  # Override any existing values
+    else:
+        print(f"Backend .env file not found at: {backend_env}")
+        # Fallback to parent directory (project root)
+        root_env = backend_dir.parent / ".env"
+        if root_env.exists():
+            print(f"Loading environment from: {root_env}")
+            load_dotenv(root_env, override=True)
+        else:
+            print(f"Root .env file not found at: {root_env}")
+else:
+    print(f"DATABASE_URL already set, skipping .env file loading")
+
+# this is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set sqlalchemy.url from environment variable
+database_url = os.getenv("DATABASE_URL")
+print(f"Retrieved DATABASE_URL: {database_url}")
+
+if database_url:
+    # Convert asyncpg to regular postgresql for migrations
+    sync_database_url = database_url.replace("postgresql+asyncpg://", "postgresql://")
+    config.set_main_option("sqlalchemy.url", sync_database_url)
+    print(f"Using database URL: {sync_database_url}")
+else:
+    raise ValueError("DATABASE_URL environment variable not found!")
+
+# add your model's MetaData object here for 'autogenerate' support
+from src.database import Base
+target_metadata = Base.metadata
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

phase-1-core-infra/backend/alembic/env_fresh.py

@@ -0,0 +1,75 @@
+from logging.config import fileConfig
+from sqlalchemy import engine_from_config
+from sqlalchemy import pool
+from alembic import context
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+
+# Load environment variables from the backend directory
+backend_dir = Path(__file__).parent  # alembic directory -> backend directory
+backend_env = backend_dir / ".env"
+if backend_env.exists():
+    load_dotenv(backend_env)
+else:
+    # Fallback to parent directory
+    root_env = backend_dir.parent.parent / ".env"
+    if root_env.exists():
+        load_dotenv(root_env)
+
+# this is the Alembic Config object
+config = context.config
+
+# Interpret the config file for Python logging
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Set sqlalchemy.url from environment variable
+database_url = os.getenv("DATABASE_URL")
+if database_url:
+    # Convert asyncpg to regular postgresql for migrations
+    sync_database_url = database_url.replace("postgresql+asyncpg://", "postgresql://")
+    config.set_main_option("sqlalchemy.url", sync_database_url)
+    print(f"Using database URL: {sync_database_url}")
+else:
+    raise ValueError("DATABASE_URL environment variable not found!")
+
+# add your model's MetaData object here for 'autogenerate' support
+from src.database import Base
+target_metadata = Base.metadata
+
+def run_migrations_offline() -> None:
+    """Run migrations in 'offline' mode."""
+    url = config.get_main_option("sqlalchemy.url")
+    context.configure(
+        url=url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    """Run migrations in 'online' mode."""
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection, target_metadata=target_metadata
+        )
+
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

phase-1-core-infra/backend/alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+# revision identifiers, used by Alembic.
+revision = ${repr(up_revision)}
+down_revision = ${repr(down_revision)}
+branch_labels = ${repr(branch_labels)}
+depends_on = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

phase-1-core-infra/backend/alembic/versions/001_initial_schema.py

@@ -0,0 +1,78 @@
+"""Initial schema for Phase 1
+
+Revision ID: 001_initial_schema
+Revises:
+Create Date: 2026-02-11
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '001_initial_schema'
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Enable UUID extension
+    op.execute('CREATE EXTENSION IF NOT EXISTS "uuid-ossp"')
+
+    # Create users table
+    op.create_table(
+        'users',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('uuid_generate_v4()')),
+        sa.Column('email', sa.String(255), nullable=False, unique=True),
+        sa.Column('hashed_password', sa.String(255), nullable=False),
+        sa.Column('name', sa.String(255), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('last_login_at', sa.DateTime(timezone=True), nullable=True),
+    )
+    op.create_index('ix_users_email', 'users', ['email'])
+    op.create_index('ix_users_created_at', 'users', ['created_at'])
+
+    # Create social_accounts table
+    op.create_table(
+        'social_accounts',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('uuid_generate_v4()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('platform', sa.String(50), nullable=False),
+        sa.Column('platform_user_id', sa.String(255), nullable=False),
+        sa.Column('access_token', sa.Text, nullable=False),
+        sa.Column('refresh_token', sa.Text, nullable=True),
+        sa.Column('token_expires_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('connection_status', sa.String(50), nullable=False, server_default='active'),
+        sa.Column('last_sync_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+    )
+    op.create_index('ix_social_accounts_user_id', 'social_accounts', ['user_id'])
+    op.create_index('ix_social_accounts_connection_status', 'social_accounts', ['connection_status'])
+    op.create_unique_constraint('uq_platform_user', 'social_accounts', ['platform', 'platform_user_id'])
+
+    # Create draft_posts table
+    op.create_table(
+        'draft_posts',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('uuid_generate_v4()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('social_account_id', postgresql.UUID(as_uuid=True), sa.ForeignKey('social_accounts.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('content', sa.Text, nullable=False),
+        sa.Column('target_platform', sa.String(50), nullable=False),
+        sa.Column('status', sa.String(50), nullable=False, server_default='draft'),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('scheduled_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('published_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('media_urls', postgresql.JSONB, nullable=True),
+    )
+    op.create_index('ix_draft_posts_user_id', 'draft_posts', ['user_id'])
+    op.create_index('ix_draft_posts_social_account_id', 'draft_posts', ['social_account_id'])
+    op.create_index('ix_draft_posts_status', 'draft_posts', ['status'])
+    op.create_index('ix_draft_posts_scheduled_at', 'draft_posts', ['scheduled_at'])
+
+
+def downgrade() -> None:
+    op.drop_table('draft_posts')
+    op.drop_table('social_accounts')
+    op.drop_table('users')
+    op.execute('DROP EXTENSION IF EXISTS "uuid-ossp"')

phase-1-core-infra/backend/alembic/versions/002_add_encryption_columns.py

@@ -0,0 +1,53 @@
+"""Add encryption columns to social_accounts table
+
+Revision ID: 002_add_encryption
+Revises: 001_initial_schema
+Create Date: 2026-02-12
+
+"""
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision = '002_add_encryption'
+down_revision = '001_initial_schema'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Add encryption columns to social_accounts table for AES-256 token encryption."""
+
+    # Add new columns for encrypted tokens
+    op.add_column('social_accounts',
+        sa.Column('encrypted_access_token', sa.Text(), nullable=True)
+    )
+    op.add_column('social_accounts',
+        sa.Column('encrypted_refresh_token', sa.Text(), nullable=True)
+    )
+    op.add_column('social_accounts',
+        sa.Column('encryption_key_version', sa.Integer(), nullable=False, server_default='1')
+    )
+
+    # Create index for key rotation queries
+    op.create_index(
+        'idx_social_accounts_encryption_key_version',
+        'social_accounts',
+        ['encryption_key_version']
+    )
+
+    # Note: Migration of existing plaintext tokens to encrypted format
+    # should be done via separate script (migrate_encrypt_tokens.py)
+    # After migration is verified, drop old plaintext columns:
+    # op.drop_column('social_accounts', 'access_token')
+    # op.drop_column('social_accounts', 'refresh_token')
+
+
+def downgrade() -> None:
+    """Remove encryption columns from social_accounts table."""
+
+    op.drop_index('idx_social_accounts_encryption_key_version', table_name='social_accounts')
+    op.drop_column('social_accounts', 'encryption_key_version')
+    op.drop_column('social_accounts', 'encrypted_refresh_token')
+    op.drop_column('social_accounts', 'encrypted_access_token')

phase-1-core-infra/backend/alembic/versions/003_create_rate_limit_rules.py

@@ -0,0 +1,51 @@
+"""Create rate_limit_rules table
+
+Revision ID: 003_rate_limit_rules
+Revises: 002_add_encryption
+Create Date: 2026-02-12
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = '003_rate_limit_rules'
+down_revision = '002_add_encryption'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create rate_limit_rules table for configuring rate limiting per endpoint."""
+
+    op.create_table(
+        'rate_limit_rules',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('endpoint_pattern', sa.String(255), nullable=False, unique=True),
+        sa.Column('requests_per_minute', sa.Integer(), nullable=False),
+        sa.Column('requests_per_hour', sa.Integer(), nullable=True),
+        sa.Column('tier_overrides', postgresql.JSONB(), nullable=False, server_default='{}'),
+        sa.Column('enabled', sa.Boolean(), nullable=False, server_default='true'),
+        sa.Column('description', sa.Text(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.CheckConstraint('requests_per_minute > 0', name='check_requests_per_minute_positive'),
+        sa.CheckConstraint(
+            'requests_per_hour IS NULL OR requests_per_hour >= requests_per_minute * 60',
+            name='check_requests_per_hour_valid'
+        )
+    )
+
+    # Create indexes for efficient lookups
+    op.create_index('idx_rate_limit_rules_endpoint', 'rate_limit_rules', ['endpoint_pattern'])
+    op.create_index('idx_rate_limit_rules_enabled', 'rate_limit_rules', ['enabled'])
+
+
+def downgrade() -> None:
+    """Drop rate_limit_rules table."""
+
+    op.drop_index('idx_rate_limit_rules_enabled', table_name='rate_limit_rules')
+    op.drop_index('idx_rate_limit_rules_endpoint', table_name='rate_limit_rules')
+    op.drop_table('rate_limit_rules')

phase-1-core-infra/backend/alembic/versions/004_create_rate_limit_violations.py

@@ -0,0 +1,61 @@
+"""Create rate_limit_violations table
+
+Revision ID: 004_rate_limit_violations
+Revises: 003_rate_limit_rules
+Create Date: 2026-02-12
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = '004_rate_limit_violations'
+down_revision = '003_rate_limit_rules'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create rate_limit_violations table for logging rate limit violations."""
+
+    op.create_table(
+        'rate_limit_violations',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), nullable=True),
+        sa.Column('ip_address', sa.String(45), nullable=False),
+        sa.Column('endpoint', sa.String(255), nullable=False),
+        sa.Column('requests_made', sa.Integer(), nullable=False),
+        sa.Column('limit_allowed', sa.Integer(), nullable=False),
+        sa.Column('window_seconds', sa.Integer(), nullable=False),
+        sa.Column('user_agent', sa.Text(), nullable=True),
+        sa.Column('violated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.CheckConstraint('requests_made > limit_allowed', name='check_violation_exceeded'),
+        sa.CheckConstraint('window_seconds > 0', name='check_window_positive')
+    )
+
+    # Add foreign key to users table (nullable for unauthenticated requests)
+    op.create_foreign_key(
+        'fk_rate_limit_violations_user_id',
+        'rate_limit_violations',
+        'users',
+        ['user_id'],
+        ['id'],
+        ondelete='SET NULL'
+    )
+
+    # Create indexes for efficient queries
+    op.create_index('idx_rate_limit_violations_user_id', 'rate_limit_violations', ['user_id'])
+    op.create_index('idx_rate_limit_violations_ip', 'rate_limit_violations', ['ip_address'])
+    op.create_index('idx_rate_limit_violations_violated_at', 'rate_limit_violations', ['violated_at'])
+
+
+def downgrade() -> None:
+    """Drop rate_limit_violations table."""
+
+    op.drop_index('idx_rate_limit_violations_violated_at', table_name='rate_limit_violations')
+    op.drop_index('idx_rate_limit_violations_ip', table_name='rate_limit_violations')
+    op.drop_index('idx_rate_limit_violations_user_id', table_name='rate_limit_violations')
+    op.drop_constraint('fk_rate_limit_violations_user_id', 'rate_limit_violations', type_='foreignkey')
+    op.drop_table('rate_limit_violations')

phase-1-core-infra/backend/alembic/versions/005_create_admin_metrics.py

@@ -0,0 +1,49 @@
+"""Create admin_metrics table
+
+Revision ID: 005_admin_metrics
+Revises: 004_rate_limit_violations
+Create Date: 2026-02-12
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+
+# revision identifiers, used by Alembic.
+revision = '005_admin_metrics'
+down_revision = '004_rate_limit_violations'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    """Create admin_metrics table for pre-computed dashboard metrics."""
+
+    op.create_table(
+        'admin_metrics',
+        sa.Column('metric_date', sa.Date(), primary_key=True),
+        sa.Column('total_users', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('active_subscriptions', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('new_users_today', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('mrr_cents', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('total_revenue_cents', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('openai_tokens_used', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('veo_videos_generated', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('ai_cost_cents', sa.BigInteger(), nullable=False, server_default='0'),
+        sa.Column('posts_published', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('approval_rate_percent', sa.Numeric(5, 2), nullable=False, server_default='0'),
+        sa.Column('avg_response_time_ms', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('error_count', sa.Integer(), nullable=False, server_default='0'),
+        sa.Column('computed_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()'))
+    )
+
+    # Create index for time-series queries
+    op.create_index('idx_admin_metrics_date', 'admin_metrics', ['metric_date'])
+
+
+def downgrade() -> None:
+    """Drop admin_metrics table."""
+
+    op.drop_index('idx_admin_metrics_date', table_name='admin_metrics')
+    op.drop_table('admin_metrics')

phase-1-core-infra/backend/alembic/versions/007_better_auth_schema.py

@@ -0,0 +1,103 @@
+"""Create Better Auth schema
+
+Revision ID: 007_better_auth_schema
+Revises: 005_create_admin_metrics
+Create Date: 2026-02-12
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision = '007_better_auth_schema'
+down_revision = '005_admin_metrics'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Alter existing users table to add Better Auth fields
+    op.add_column('users', sa.Column('email_verified', sa.Boolean(), nullable=False, server_default='false'))
+    op.add_column('users', sa.Column('image', sa.Text(), nullable=True))
+    op.add_column('users', sa.Column('is_admin', sa.Boolean(), nullable=False, server_default='false'))
+    op.add_column('users', sa.Column('clerk_id', sa.String(255), nullable=True, unique=True))
+    op.add_column('users', sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')))
+
+    # Rename hashed_password to password_hash for Better Auth compatibility
+    op.alter_column('users', 'hashed_password', new_column_name='password_hash')
+
+    # Create index for clerk_id
+    op.create_index('idx_users_clerk_id', 'users', ['clerk_id'])
+
+    # Create sessions table
+    op.create_table(
+        'sessions',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column('token', sa.Text(), nullable=False, unique=True),
+        sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('ip_address', sa.String(45), nullable=True),
+        sa.Column('user_agent', sa.Text(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+    )
+
+    # Create indexes for sessions table
+    op.create_index('idx_sessions_user_id', 'sessions', ['user_id'])
+    op.create_index('idx_sessions_token', 'sessions', ['token'])
+    op.create_index('idx_sessions_expires_at', 'sessions', ['expires_at'])
+
+    # Create accounts table (OAuth providers)
+    op.create_table(
+        'accounts',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True), nullable=False),
+        sa.Column('provider', sa.String(50), nullable=False),
+        sa.Column('provider_account_id', sa.String(255), nullable=False),
+        sa.Column('access_token', sa.Text(), nullable=True),
+        sa.Column('refresh_token', sa.Text(), nullable=True),
+        sa.Column('expires_at', sa.DateTime(timezone=True), nullable=True),
+        sa.Column('token_type', sa.String(50), nullable=True),
+        sa.Column('scope', sa.Text(), nullable=True),
+        sa.Column('id_token', sa.Text(), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.Column('updated_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+        sa.ForeignKeyConstraint(['user_id'], ['users.id'], ondelete='CASCADE'),
+        sa.UniqueConstraint('provider', 'provider_account_id', name='uq_provider_account'),
+    )
+
+    # Create indexes for accounts table
+    op.create_index('idx_accounts_user_id', 'accounts', ['user_id'])
+    op.create_index('idx_accounts_provider', 'accounts', ['provider', 'provider_account_id'])
+
+    # Create verification_tokens table
+    op.create_table(
+        'verification_tokens',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True, server_default=sa.text('gen_random_uuid()')),
+        sa.Column('identifier', sa.String(255), nullable=False),
+        sa.Column('token', sa.Text(), nullable=False, unique=True),
+        sa.Column('expires_at', sa.DateTime(timezone=True), nullable=False),
+        sa.Column('type', sa.String(50), nullable=False),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False, server_default=sa.text('NOW()')),
+    )
+
+    # Create indexes for verification_tokens table
+    op.create_index('idx_verification_tokens_token', 'verification_tokens', ['token'])
+    op.create_index('idx_verification_tokens_identifier', 'verification_tokens', ['identifier'])
+
+
+def downgrade() -> None:
+    # Drop new tables
+    op.drop_table('verification_tokens')
+    op.drop_table('accounts')
+    op.drop_table('sessions')
+
+    # Revert users table changes
+    op.drop_index('idx_users_clerk_id', 'users')
+    op.alter_column('users', 'password_hash', new_column_name='hashed_password')
+    op.drop_column('users', 'updated_at')
+    op.drop_column('users', 'clerk_id')
+    op.drop_column('users', 'is_admin')
+    op.drop_column('users', 'image')
+    op.drop_column('users', 'email_verified')

phase-1-core-infra/backend/alembic/versions/008_add_post_logs_and_twitter.py

@@ -0,0 +1,50 @@
+"""Add post_logs table and Twitter platform support
+
+Revision ID: 008_add_post_logs_and_twitter
+Revises: 007_better_auth_schema
+Create Date: 2026-03-01
+
+"""
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers
+revision = '008_add_post_logs_and_twitter'
+down_revision = '007_better_auth_schema'
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    # Make social_account_id nullable in draft_posts (posts can exist without a specific account)
+    op.alter_column('draft_posts', 'social_account_id', nullable=True)
+
+    # Create post_logs table
+    # platform and status stored as VARCHAR(50) - consistent with existing schema
+    op.create_table(
+        'post_logs',
+        sa.Column('id', postgresql.UUID(as_uuid=True), primary_key=True),
+        sa.Column('post_id', postgresql.UUID(as_uuid=True),
+                  sa.ForeignKey('draft_posts.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('user_id', postgresql.UUID(as_uuid=True),
+                  sa.ForeignKey('users.id', ondelete='CASCADE'), nullable=False),
+        sa.Column('platform', sa.String(50), nullable=False),
+        sa.Column('status', sa.String(50), nullable=False, server_default='failed'),
+        sa.Column('message', sa.Text(), nullable=True),
+        sa.Column('platform_post_id', sa.String(255), nullable=True),
+        sa.Column('created_at', sa.DateTime(timezone=True), nullable=False,
+                  server_default=sa.text('NOW()')),
+    )
+
+    op.create_index('ix_post_logs_post_id', 'post_logs', ['post_id'])
+    op.create_index('ix_post_logs_user_id', 'post_logs', ['user_id'])
+    op.create_index('ix_post_logs_status', 'post_logs', ['status'])
+
+
+def downgrade() -> None:
+    op.drop_index('ix_post_logs_status', table_name='post_logs')
+    op.drop_index('ix_post_logs_user_id', table_name='post_logs')
+    op.drop_index('ix_post_logs_post_id', table_name='post_logs')
+    op.drop_table('post_logs')
+    op.alter_column('draft_posts', 'social_account_id', nullable=False)

phase-1-core-infra/backend/pyproject.toml

@@ -0,0 +1,22 @@
+[tool.black]
+line-length = 100
+target-version = ['py311']
+include = '\.pyi?$'
+
+[tool.isort]
+profile = "black"
+line_length = 100
+
+[tool.mypy]
+python_version = "3.11"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+asyncio_mode = "auto"

phase-1-core-infra/backend/requirements-dev.txt

@@ -0,0 +1,14 @@
+# Testing
+pytest==7.4.3
+pytest-asyncio==0.21.1
+pytest-cov==4.1.0
+httpx==0.25.2
+
+# Linting and formatting
+black==23.12.0
+flake8==6.1.0
+mypy==1.7.1
+isort==5.13.2
+
+# Type stubs
+types-passlib==1.7.7.20260211

phase-1-core-infra/backend/requirements.txt

@@ -0,0 +1,36 @@
+# FastAPI and ASGI server
+fastapi>=0.104.1
+uvicorn[standard]>=0.24.0
+python-multipart>=0.0.6
+
+# Database
+sqlalchemy[asyncio]>=2.0.23
+asyncpg>=0.29.0
+psycopg2-binary>=2.9.9
+alembic>=1.13.0
+
+# Data validation
+pydantic>=2.5.0
+pydantic-settings>=2.1.0
+email-validator>=2.1.0
+
+# Authentication and security
+passlib[bcrypt]>=1.7.4
+pyjwt>=2.8.0
+cryptography>=41.0.7
+
+# HTTP client for OAuth
+httpx>=0.25.2
+
+# Environment variables
+python-dotenv>=1.0.0
+
+# Rate limiting
+slowapi>=0.1.9
+
+# Redis client
+redis>=5.0.1
+
+# AI Content Generation
+openai>=1.12.0
+google-generativeai>=0.4.0