BACKEND FIX: Filter by credential provider during login

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.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`.

Chatbot/.env

@@ -0,0 +1 @@
+DATABASE_URL=postgresql://neondb_owner:npg_O1mLbVXkfEY5@ep-broad-fog-a4ba5mi3-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require

Chatbot/.pytest_cache/CACHEDIR.TAG

@@ -0,0 +1,4 @@
+Signature: 8a477f597d28d172789f06886806bc55
+# This file is a cache directory tag created by pytest.
+# For information about cache directory tags, see:
+#	https://bford.info/cachedir/spec.html

Chatbot/.pytest_cache/README.md

@@ -0,0 +1,8 @@
+# pytest cache directory #
+
+This directory contains data from the pytest's cache plugin,
+which provides the `--lf` and `--ff` options, as well as the `cache` fixture.
+
+**Do not** commit this to version control.
+
+See [the docs](https://docs.pytest.org/en/stable/how-to/cache.html) for more information.

Chatbot/.pytest_cache/v/cache/lastfailed

@@ -0,0 +1 @@
+{}

Chatbot/.pytest_cache/v/cache/nodeids

@@ -0,0 +1,111 @@
+[
+  "tests/integration/test_add_task_integration.py::test_data_isolation_different_users",
+  "tests/integration/test_add_task_integration.py::test_multiple_tasks_same_user",
+  "tests/integration/test_add_task_integration.py::test_task_created_with_correct_user_association",
+  "tests/integration/test_add_task_integration.py::test_task_creation_persists_across_sessions",
+  "tests/integration/test_add_task_integration.py::test_task_user_id_cannot_be_modified",
+  "tests/integration/test_add_task_integration.py::test_task_without_description",
+  "tests/integration/test_conversation_persistence.py::test_conversation_creation_and_retrieval",
+  "tests/integration/test_conversation_persistence.py::test_conversation_update_timestamp",
+  "tests/integration/test_conversation_persistence.py::test_conversation_with_messages_deletion",
+  "tests/integration/test_conversation_persistence.py::test_multi_message_scenario",
+  "tests/integration/test_conversation_persistence.py::test_multiple_conversations_per_user",
+  "tests/integration/test_conversation_persistence.py::test_retrieval_order_chronological",
+  "tests/integration/test_mcp_tool_integration.py::test_empty_list_handles_gracefully",
+  "tests/integration/test_mcp_tool_integration.py::test_full_workflow_add_list_complete_update_delete",
+  "tests/integration/test_mcp_tool_integration.py::test_idempotent_complete_task",
+  "tests/integration/test_mcp_tool_integration.py::test_multiple_users_isolated_workflow",
+  "tests/integration/test_mcp_tool_integration.py::test_update_preserves_completion_status",
+  "tests/integration/test_message_persistence.py::test_cross_session_retrieval_chronological",
+  "tests/integration/test_message_persistence.py::test_empty_conversation_start",
+  "tests/integration/test_message_persistence.py::test_message_persistence_across_sessions",
+  "tests/integration/test_message_persistence.py::test_message_roles_persist",
+  "tests/integration/test_message_persistence.py::test_message_survives_server_restart_simulation",
+  "tests/integration/test_message_persistence.py::test_message_tool_calls_persistence",
+  "tests/integration/test_message_persistence.py::test_user_isolation_in_messages",
+  "tests/security/test_user_isolation.py::test_add_task_only_creates_for_specified_user",
+  "tests/security/test_user_isolation.py::test_complete_task_requires_user_ownership",
+  "tests/security/test_user_isolation.py::test_delete_task_requires_user_ownership",
+  "tests/security/test_user_isolation.py::test_empty_user_id_rejected",
+  "tests/security/test_user_isolation.py::test_list_tasks_only_returns_user_own_tasks",
+  "tests/security/test_user_isolation.py::test_multiple_users_cannot_see_each_others_tasks",
+  "tests/security/test_user_isolation.py::test_not_found_does_not_leak_ownership",
+  "tests/security/test_user_isolation.py::test_update_task_requires_user_ownership",
+  "tests/security/test_user_isolation.py::test_whitespace_only_user_id_rejected",
+  "tests/unit/test_add_task_error_handling.py::test_error_codes_are_constants",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_database_error",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_description_too_long",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_empty_title",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_missing_user_id",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_title_too_long",
+  "tests/unit/test_add_task_error_handling.py::test_error_handling_whitespace_only_title",
+  "tests/unit/test_add_task_error_handling.py::test_error_response_format",
+  "tests/unit/test_add_task_error_handling.py::test_multiple_validation_errors_first_one_returned",
+  "tests/unit/test_add_task_error_handling.py::test_no_raw_database_errors_exposed",
+  "tests/unit/test_add_task_tool.py::test_add_task_description_validation_too_long",
+  "tests/unit/test_add_task_tool.py::test_add_task_max_description",
+  "tests/unit/test_add_task_tool.py::test_add_task_max_title",
+  "tests/unit/test_add_task_tool.py::test_add_task_minimal_title",
+  "tests/unit/test_add_task_tool.py::test_add_task_returns_correct_format",
+  "tests/unit/test_add_task_tool.py::test_add_task_special_characters_in_description",
+  "tests/unit/test_add_task_tool.py::test_add_task_special_characters_in_title",
+  "tests/unit/test_add_task_tool.py::test_add_task_title_validation_empty",
+  "tests/unit/test_add_task_tool.py::test_add_task_title_validation_too_long",
+  "tests/unit/test_add_task_tool.py::test_add_task_title_validation_too_short",
+  "tests/unit/test_add_task_tool.py::test_add_task_user_association",
+  "tests/unit/test_add_task_tool.py::test_add_task_valid_input",
+  "tests/unit/test_add_task_tool.py::test_add_task_without_description",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_already_complete",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_filters_by_user_id",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_invalid_task_id",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_invalid_user_id",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_not_found",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_response_format",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_success",
+  "tests/unit/test_complete_task_tool.py::test_complete_task_updates_completed_field",
+  "tests/unit/test_conversation_model.py::test_conversation_creation",
+  "tests/unit/test_conversation_model.py::test_conversation_fields",
+  "tests/unit/test_conversation_model.py::test_conversation_relationships",
+  "tests/unit/test_conversation_model.py::test_conversation_str_representation",
+  "tests/unit/test_conversation_model.py::test_conversation_table_name",
+  "tests/unit/test_conversation_model.py::test_conversation_timestamps_auto",
+  "tests/unit/test_conversation_model.py::test_conversation_user_id_required",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_filters_by_user_id",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_invalid_task_id",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_invalid_user_id",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_not_found",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_ownership_verification",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_response_format",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_returns_title",
+  "tests/unit/test_delete_task_tool.py::test_delete_task_success",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_all_tasks",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_completed_only",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_default_status_all",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_empty_list",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_filters_by_user_id",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_invalid_status",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_pending_only",
+  "tests/unit/test_list_tasks_tool.py::test_list_tasks_response_format",
+  "tests/unit/test_message_model.py::test_message_content_required",
+  "tests/unit/test_message_model.py::test_message_creation",
+  "tests/unit/test_message_model.py::test_message_fields",
+  "tests/unit/test_message_model.py::test_message_long_content",
+  "tests/unit/test_message_model.py::test_message_role_validation",
+  "tests/unit/test_message_model.py::test_message_table_name",
+  "tests/unit/test_message_model.py::test_message_timestamps_auto",
+  "tests/unit/test_message_model.py::test_message_tool_calls_optional",
+  "tests/unit/test_message_model.py::test_message_with_tool_calls",
+  "tests/unit/test_update_task_tool.py::test_update_task_both_fields",
+  "tests/unit/test_update_task_tool.py::test_update_task_description_only",
+  "tests/unit/test_update_task_tool.py::test_update_task_empty_title",
+  "tests/unit/test_update_task_tool.py::test_update_task_filters_by_user_id",
+  "tests/unit/test_update_task_tool.py::test_update_task_invalid_description_length",
+  "tests/unit/test_update_task_tool.py::test_update_task_invalid_task_id",
+  "tests/unit/test_update_task_tool.py::test_update_task_invalid_title_length",
+  "tests/unit/test_update_task_tool.py::test_update_task_invalid_user_id",
+  "tests/unit/test_update_task_tool.py::test_update_task_neither_field",
+  "tests/unit/test_update_task_tool.py::test_update_task_not_found",
+  "tests/unit/test_update_task_tool.py::test_update_task_response_format",
+  "tests/unit/test_update_task_tool.py::test_update_task_title_only",
+  "tests/unit/test_update_task_tool.py::test_update_task_whitespace_only_title"
+]

Chatbot/.pytest_cache/v/cache/stepwise

@@ -0,0 +1 @@
+[]

Chatbot/.specify/memory/constitution.md

@@ -0,0 +1,274 @@
+<!--
+SYNC IMPACT REPORT
+================================================================================
+Version Change: None → 1.0.0
+Rationale: Initial constitution ratification for Phase 3 - AI-Powered Todo Chatbot
+================================================================================
+Modified Principles: None (initial creation)
+Added Sections:
+  - Vision Statement
+  - Core Architectural Principles (5 principles)
+  - Technology Stack (Non-Negotiable)
+  - Database Schema Requirements
+  - MCP Tools Specification (5 tools)
+  - Request Flow Architecture
+  - User Experience Standards
+  - Security Requirements
+  - Performance Requirements
+  - Testing Standards
+  - Spec-Driven Development Workflow
+  - Forbidden Practices
+  - Deliverables Checklist
+  - Success Metrics
+  - Version History
+  - Support & References
+Removed Sections: None (initial creation)
+Templates requiring updates:
+  ✅ plan-template.md - Constitution Check section aligns with principles
+  ✅ spec-template.md - Structure supports constitution requirements
+  ✅ tasks-template.md - Task categorization reflects implementation workflow
+  ✅ All other templates - No outdated references detected
+Follow-up TODOs: None
+================================================================================
+-->
+
+# Chatbot Phase 3 Constitution
+
+## Core Principles
+
+### I. Stateless Server Architecture
+Server maintains NO state in memory. Every request must be independently processable with all conversation state persisted in PostgreSQL database. Enables horizontal scaling, fault tolerance, and resilience.
+
+### II. MCP-First Tool Design
+All task operations exposed ONLY through MCP tools (5 total: add, list, complete, delete, update). Direct database calls from chat endpoint are forbidden. Standardized interface for AI agent interaction.
+
+### III. AI Agent Orchestration
+OpenAI Agents SDK orchestrates all tool calls. Agent analyzes user intent and selects appropriate tools based on natural language understanding. No manual if-else routing in chat endpoint.
+
+### IV. Conversation Persistence
+Every message stored in database with conversation context. Chat history survives server restarts and enables multi-device access. Conversation and Message tables with proper relationships. No in-memory conversation buffers.
+
+### V. Security-First JWT Authentication
+Every chat request must include valid JWT token. User isolation and authorization enforcement through Better Auth JWT integration from Phase 2. All MCP tools verify user_id from token.
+
+## Technology Stack (Non-Negotiable)
+
+### Frontend
+- **Framework**: OpenAI ChatKit (purpose-built for conversational AI interfaces)
+- **Configuration**: Domain allowlist required for production
+
+### Backend
+- **Framework**: Python FastAPI (async support, modern Python, excellent OpenAPI integration)
+
+### AI Layer
+- **Framework**: OpenAI Agents SDK (official SDK with tool calling support)
+- **Model**: GPT-4 or GPT-4-Turbo
+
+### MCP Server
+- **Framework**: Official MCP SDK (Python) (standard protocol for AI-tool communication)
+
+### Database
+- **Service**: Neon Serverless PostgreSQL (from Phase 2)
+- **ORM**: SQLModel (async support, Pydantic integration, type safety)
+
+### Authentication
+- **Service**: Better Auth (from Phase 2)
+- **Token**: JWT with 7-day expiry
+
+## Database Schema Requirements
+
+### New Tables (Phase 3)
+
+#### Conversation Table
+```sql
+CREATE TABLE conversations (
+    id SERIAL PRIMARY KEY,
+    user_id VARCHAR(255) NOT NULL,
+    created_at TIMESTAMP DEFAULT NOW(),
+    updated_at TIMESTAMP DEFAULT NOW(),
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    INDEX idx_user_conversations (user_id, created_at DESC)
+);
+```
+
+#### Message Table
+```sql
+CREATE TABLE messages (
+    id SERIAL PRIMARY KEY,
+    conversation_id INTEGER NOT NULL,
+    user_id VARCHAR(255) NOT NULL,
+    role VARCHAR(20) NOT NULL CHECK (role IN ('user', 'assistant')),
+    content TEXT NOT NULL,
+    tool_calls JSONB,
+    created_at TIMESTAMP DEFAULT NOW(),
+    FOREIGN KEY (conversation_id) REFERENCES conversations(id) ON DELETE CASCADE,
+    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
+    INDEX idx_conversation_messages (conversation_id, created_at ASC)
+);
+```
+
+### Existing Tables (Phase 2)
+- **tasks**: Already exists with user_id foreign key
+- **users**: Managed by Better Auth
+
+## MCP Tools Specification
+
+### Tool Contract Standards
+- **Input Validation**: Pydantic models for all parameters
+- **Error Handling**: Return structured error objects, never raise exceptions
+- **User Isolation**: Every tool MUST filter by user_id from JWT
+- **Idempotency**: Operations should be safe to retry
+- **Response Format**: Consistent JSON structure across all tools
+
+### Required Tools (5 Total)
+
+#### 1. add_task
+Parameters:
+  - user_id: str (from JWT)
+  - title: str (1-200 chars, required)
+  - description: str (0-1000 chars, optional)
+
+Returns:
+  {
+    "task_id": int,
+    "status": "created",
+    "title": str
+  }
+
+#### 2. list_tasks
+Parameters:
+  - user_id: str (from JWT)
+  - status: str (optional: "all" | "pending" | "completed")
+
+Returns:
+  {
+    "tasks": [
+      {"id": int, "title": str, "completed": bool, "created_at": str}
+    ],
+    "total": int
+  }
+
+#### 3. complete_task
+Parameters:
+  - user_id: str (from JWT)
+  - task_id: int (required)
+
+Returns:
+  {
+    "task_id": int,
+    "status": "completed",
+    "title": str
+  }
+
+#### 4. delete_task
+Parameters:
+  - user_id: str (from JWT)
+  - task_id: int (required)
+
+Returns:
+  {
+    "task_id": int,
+    "status": "deleted",
+    "title": str
+  }
+
+#### 5. update_task
+Parameters:
+  - user_id: str (from JWT)
+  - task_id: int (required)
+  - title: str (optional, 1-200 chars)
+  - description: str (optional, 0-1000 chars)
+
+Returns:
+  {
+    "task_id": int,
+    "status": "updated",
+    "title": str
+  }
+
+## Security Requirements
+
+### JWT Token Validation
+Every chat request MUST validate:
+1. Token present in Authorization header
+2. Token signature valid (using BETTER_AUTH_SECRET)
+3. Token not expired
+4. user_id from token matches {user_id} in URL
+
+### User Data Isolation
+Every MCP tool MUST enforce:
+1. Filter all queries by user_id from JWT
+2. Never expose other users' tasks
+3. Validate task ownership before update/delete
+4. Return 404 instead of 403 for missing tasks (security by obscurity)
+
+### SQL Injection Prevention
+All database queries MUST use:
+1. SQLModel ORM (parameterized queries)
+2. Never string concatenation
+3. Input validation via Pydantic
+
+## Performance Requirements
+
+### Response Time
+- **Chat endpoint**: < 3 seconds (95th percentile)
+- **MCP tool execution**: < 500ms per tool
+- **Database queries**: < 100ms per query
+
+### Scalability
+- **Stateless design**: Supports horizontal scaling
+- **Database pooling**: Connection reuse for efficiency
+- **Async operations**: Non-blocking I/O throughout
+
+## Testing Standards
+
+### Unit Tests Required
+- Each MCP tool independently testable
+- Mock database for tool tests
+- JWT verification logic tested
+
+### Integration Tests Required
+- End-to-end chat flow
+- Conversation persistence
+- Multi-turn conversations
+
+### User Acceptance Tests
+- Natural language variations
+- Error scenarios
+- Conversation history
+
+## Spec-Driven Development Workflow
+
+### Process (NON-NEGOTIABLE)
+1. Write Constitution (this file)
+2. Write Specification for each component
+3. Get Claude Code to generate implementation
+4. NO MANUAL CODING ALLOWED
+5. Refine spec if output incorrect
+6. Iterate until code correct
+
+### Spec Requirements
+Every spec MUST include:
+- **What**: Clear requirement statement
+- **Why**: Rationale and context
+- **How**: Technical approach
+- **Acceptance Criteria**: Testable success conditions
+- **Examples**: Input/output samples
+
+## Forbidden Practices
+
+What NOT to Do:
+- Store conversation state in server memory
+- Bypass MCP tools with direct database calls from chat endpoint
+- Manual if-else routing instead of agent intelligence
+- Skip JWT validation for any request
+- Write code manually (violates spec-driven approach)
+- Use localStorage/sessionStorage (not supported in artifacts)
+- Hardcode API keys or secrets
+- Return raw database errors to users
+
+## Governance
+
+This constitution is the supreme authority for Phase 3 development. All code, specs, and decisions must align with these principles. Amendments require documentation and version updates per semantic versioning rules.
+
+**Version**: 1.0.0 | **Ratified**: 2026-01-08 | **Last Amended**: 2026-01-08

Chatbot/.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

Chatbot/.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"; }
+

Chatbot/.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

Chatbot/.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

Chatbot/.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

Chatbot/.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
+

Chatbot/.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
+

Chatbot/.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 -->

Chatbot/.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 -->

Chatbot/.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

Chatbot/.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}}

Chatbot/.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] |

Chatbot/.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%"]

Chatbot/.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

Chatbot/CLAUDE.md

@@ -0,0 +1,217 @@
+# 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.
+
+## Active Technologies
+- Python 3.11 + FastAPI 0.104+, SQLModel 0.0.14+, Pydantic 2.0+, mcp python-sdk, OpenAI Agents SDK, asyncpg 0.29+ (004-chatbot-db-mcp)
+- Neon Serverless PostgreSQL (existing from Phase 2) (004-chatbot-db-mcp)
+
+## Recent Changes
+- 004-chatbot-db-mcp: Added Python 3.11 + FastAPI 0.104+, SQLModel 0.0.14+, Pydantic 2.0+, mcp python-sdk, OpenAI Agents SDK, asyncpg 0.29+

Chatbot/README.md

@@ -0,0 +1,187 @@
+# Conversational AI Chatbot Foundation
+
+This project implements a conversational AI chatbot foundation with persistent conversation history and integrated task management tools.
+
+## Features
+
+- **Persistent Chat History**: All conversations and messages are stored in the database
+- **Task Management**: 5 standardized MCP tools for managing tasks (add, list, complete, update, delete)
+- **User Isolation**: Complete data isolation between users
+- **Natural Language Processing**: Designed for integration with AI assistants
+- **Security**: JWT-based authentication and authorization
+
+## Architecture
+
+- **Backend**: Python 3.11 with FastAPI
+- **Database**: PostgreSQL (Neon Serverless)
+- **ORM**: SQLModel
+- **Protocol**: Model Context Protocol (MCP) for tool integration
+- **Testing**: pytest for unit, integration, and security tests
+
+## Technology Stack
+
+- Python 3.11
+- FastAPI 0.104+
+- SQLModel 0.0.14+
+- Pydantic 2.0+
+- mcp python-sdk
+- OpenAI Agents SDK
+- asyncpg 0.29+
+- PostgreSQL (Neon Serverless)
+
+## Installation
+
+1. Clone the repository
+2. Create a virtual environment:
+   ```bash
+   python -m venv venv
+   source venv/bin/activate  # On Windows: venv\Scripts\activate
+   ```
+3. Install dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+4. Set up environment variables:
+   ```bash
+   cp .env.example .env
+   # Edit .env with your database credentials
+   ```
+
+## Database Setup
+
+1. Create a PostgreSQL database (Neon recommended)
+2. Update the `DATABASE_URL` in your `.env` file:
+   ```env
+   DATABASE_URL="postgresql://your_username:your_password@ep-xxx.us-east-1.aws.neon.tech/chatbot_db?sslmode=require"
+   ```
+3. Run the database migrations to create the required tables:
+   ```bash
+   python backend/db.py  # Or use your migration system
+   ```
+
+## Running the Application
+
+1. Start the MCP server:
+   ```bash
+   python -m backend.mcp_server.server
+   ```
+
+## MCP Tools
+
+The application exposes 5 standardized task management tools via the Model Context Protocol:
+
+### 1. add_task
+Create a new task for a user
+- Parameters: `user_id`, `title` (1-200 chars), `description` (optional, 0-1000 chars)
+
+### 2. list_tasks
+List tasks for a user with optional status filter
+- Parameters: `user_id`, `status` (all, pending, completed)
+
+### 3. complete_task
+Mark a task as completed
+- Parameters: `user_id`, `task_id`
+
+### 4. delete_task
+Delete a task
+- Parameters: `user_id`, `task_id`
+
+### 5. update_task
+Update task title and/or description
+- Parameters: `user_id`, `task_id`, `title` (optional), `description` (optional)
+
+## Testing
+
+Run the full test suite:
+```bash
+python -m pytest tests/ -v
+```
+
+Run specific test categories:
+```bash
+# Unit tests
+python -m pytest tests/unit/
+
+# Integration tests
+python -m pytest tests/integration/
+
+# Security tests
+python -m pytest tests/security/
+```
+
+## Project Structure
+
+```
+backend/
+├── models/                 # Database models (Conversation, Message, Task)
+├── mcp_server/            # MCP server implementation
+│   ├── server.py          # Main MCP server
+│   ├── schemas.py         # Pydantic schemas for tools
+│   └── tools/             # Individual MCP tools
+│       ├── add_task.py
+│       ├── list_tasks.py
+│       ├── complete_task.py
+│       ├── delete_task.py
+│       └── update_task.py
+├── db.py                  # Database connection
+└── migrations/            # Database migrations
+
+tests/
+├── unit/                  # Unit tests for individual components
+├── integration/           # Integration tests
+└── security/              # Security tests
+```
+
+## Database Schema
+
+### conversations table
+- `id`: Primary key
+- `user_id`: Foreign key to users table
+- `created_at`: Timestamp
+- `updated_at`: Timestamp
+
+### messages table
+- `id`: Primary key
+- `conversation_id`: Foreign key to conversations table
+- `user_id`: Foreign key to users table
+- `role`: 'user' or 'assistant'
+- `content`: Message text content
+- `tool_calls`: JSONB for tool invocation metadata
+- `created_at`: Timestamp
+
+### tasks table
+- `id`: Primary key
+- `user_id`: Foreign key to users table
+- `title`: Task title
+- `description`: Optional task description
+- `completed`: Boolean completion status
+- `created_at`: Timestamp
+- `updated_at`: Timestamp
+
+## Security Features
+
+- User data isolation: All queries filter by user_id
+- Input validation: All parameters validated before database operations
+- Error handling: Structured error responses without sensitive information
+- Authentication: Designed for JWT-based authentication
+
+## Development
+
+To add new MCP tools:
+1. Create a new tool in `backend/mcp_server/tools/`
+2. Follow the same pattern as existing tools
+3. Add corresponding unit and integration tests
+4. Register the tool in the MCP server
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass
+6. Submit a pull request
+
+## License
+
+[Specify your license here]

Chatbot/RUN_ME_FIRST.txt

@@ -0,0 +1,63 @@
+# How to Run Your Chatbot Application
+
+## Option 1: Run the HTTP API Server (Recommended for testing)
+
+1. Open Command Prompt as Administrator
+2. Navigate to the Chatbot directory:
+   ```
+   cd E:\hackatone_phase_03\Chatbot
+   ```
+3. Install required packages:
+   ```
+   pip install fastapi uvicorn
+   ```
+4. Run the HTTP server:
+   ```
+   uvicorn backend.http_server:app --host 0.0.0.0 --port 8000 --reload
+   ```
+5. Open your browser and go to:
+   http://localhost:8000/docs
+
+   This will show you the API documentation where you can test all tools!
+
+## Option 2: Database Setup (Required for full functionality)
+
+1. Set up your .env file with database credentials:
+   ```
+   DATABASE_URL="postgresql://your_username:your_password@ep-xxx.us-east-1.aws.neon.tech/chatbot_db?sslmode=require"
+   ```
+
+2. Or for local testing with SQLite, you can temporarily modify db.py to use:
+   ```
+   DATABASE_URL = os.getenv("DATABASE_URL", "sqlite:///./test.db")
+   ```
+
+## Option 3: Quick Test (No Database Required)
+
+All your MCP tools are working correctly! You can test them with the following:
+
+1. Run the test:
+   ```
+   python test_simple.py
+   ```
+
+## Test Commands for Chatbot
+
+Once the HTTP server is running, you can test:
+
+- Add a task: POST to `/tasks/add` with user_id, title
+- List tasks: GET to `/tasks/list?user_id=test&status=all`
+- Complete task: POST to `/tasks/complete` with user_id, task_id
+- Update task: POST to `/tasks/update` with user_id, task_id, title
+- Delete task: POST to `/tasks/delete` with user_id, task_id
+
+## Your MCP Tools Are Ready!
+
+All 5 MCP tools are implemented and working:
+1. ✓ add_task
+2. ✓ list_tasks
+3. ✓ complete_task
+4. ✓ delete_task
+5. ✓ update_task
+
+The only thing missing is a real database connection. With a proper database, your chatbot will be fully functional!

Chatbot/backend/__init__.py

@@ -0,0 +1 @@
+# Backend package

Chatbot/backend/cleanup_db.py

@@ -0,0 +1,23 @@
+from backend.db import get_engine
+from sqlalchemy import text
+from sqlmodel import SQLModel
+
+engine = get_engine()
+
+print("Dropping conversation and message tables to fix FK constraints...")
+with engine.connect() as conn:
+    # Drop in correct order due to FK
+    conn.execute(text("DROP TABLE IF EXISTS messages CASCADE"))
+    conn.execute(text("DROP TABLE IF EXISTS conversations CASCADE"))
+    conn.commit()
+print("Tables dropped successfully.")
+
+print("Recreating tables from models...")
+# This will recreate conversations and messages with the correct FK to 'user'
+from backend.models.user import User
+from backend.models.task import Task
+from backend.models.conversation import Conversation
+from backend.models.message import Message
+
+SQLModel.metadata.create_all(engine)
+print("Tables recreated successfully with correct constraints.")

Chatbot/backend/db.py

@@ -0,0 +1,61 @@
+"""
+Database connection and engine configuration.
+
+This module provides the database engine for SQLModel.
+"""
+
+from sqlmodel import create_engine, SQLModel
+from typing import Optional
+import os
+from pathlib import Path
+from dotenv import load_dotenv
+from datetime import datetime
+
+# Database URL from environment variable
+# Professional Fallback to ensure same NEON DB as Backend/Frontend
+DATABASE_URL = os.getenv("DATABASE_URL") or "postgresql://neondb_owner:npg_O1mLbVXkfEY5@ep-broad-fog-a4ba5mi3-pooler.us-east-1.aws.neon.tech/neondb?sslmode=require"
+
+# Create database engine with pooling options for stability
+engine = create_engine(
+    DATABASE_URL, 
+    echo=False,
+    pool_pre_ping=True,
+    pool_recycle=300
+)
+
+
+def get_engine():
+    """Get the database engine."""
+    return engine
+
+
+def init_db():
+    """Initialize database tables and seed default data."""
+    from backend.models.user import User
+    from backend.models.task import Task
+    from backend.models.conversation import Conversation
+    from backend.models.message import Message
+    from sqlmodel import Session, select
+
+    # Create tables
+    SQLModel.metadata.create_all(engine)
+
+    # Seed default user if none exists (for development/demo)
+    with Session(engine) as session:
+        # Check for user '1' as a string
+        statement = select(User).where(User.id == "1")
+        results = session.exec(statement)
+        user = results.first()
+
+        if not user:
+            print("Seeding default demo user...")
+            demo_user = User(
+                id="1",
+                email="demo@example.com",
+                emailVerified=True,
+                createdAt=datetime.utcnow(),
+                updatedAt=datetime.utcnow()
+            )
+            session.add(demo_user)
+            session.commit()
+            print("Default user created (ID: '1')")

Chatbot/backend/http_server.py

@@ -0,0 +1,319 @@
+"""
+ELITE NEURAL COMMANDER - VERSION 3.8.0 (GROQ LIGHTNING)
+Built by Fiza Nazz for TODOAI Engine.
+Powered by Groq AI - Ultra-fast, Unlimited Free Tier
+"""
+
+import sys
+from pathlib import Path
+import os
+import json
+import asyncio
+import logging
+from datetime import datetime, timedelta
+from typing import Optional, List, Dict, Any
+from dotenv import load_dotenv
+
+# --- ADVANCED ENVIRONMENT SYNC ---
+current_dir = Path(__file__).resolve().parent
+backend_env = current_dir.parent.parent / "backend" / ".env"
+load_dotenv(backend_env)
+
+# --- SYSTEM PATH CONFIG ---
+root_path = Path(__file__).resolve().parent.parent
+if str(root_path) not in sys.path:
+    sys.path.append(str(root_path))
+
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+from contextlib import asynccontextmanager
+from sqlmodel import Session, select, delete
+
+# Internal Imports
+try:
+    from backend.db import init_db, get_engine
+    from backend.models import Conversation, Message, Task
+    from backend.mcp_server.tools.add_task import add_task
+    from backend.mcp_server.tools.list_tasks import list_tasks
+    from backend.mcp_server.tools.complete_task import complete_task
+    from backend.mcp_server.tools.delete_task import delete_task
+    from backend.mcp_server.tools.update_task import update_task
+    from backend.mcp_server.tools.delete_all_tasks import delete_all_tasks
+except ImportError:
+    # Local fallback for direct execution
+    from db import init_db, get_engine
+    from models import Conversation, Message, Task
+    from mcp_server.tools.add_task import add_task
+    from mcp_server.tools.list_tasks import list_tasks
+    from mcp_server.tools.complete_task import complete_task
+    from mcp_server.tools.delete_task import delete_task
+    from mcp_server.tools.update_task import update_task
+    from mcp_server.tools.delete_all_tasks import delete_all_tasks
+
+# --- ELITE AI ENGINE (GROQ LIGHTNING - UNLIMITED FREE) ---
+# Groq provides 30 requests/minute with super-fast inference
+AI_MODELS = [
+    "llama-3.3-70b-versatile",   # Primary: Groq's latest and most stable model
+    "llama-3.1-8b-instant",      # Backup
+    "gemma2-9b-it"               # Alternative
+]
+
+client = None
+api_key = os.getenv("GROQ_API_KEY")  # Changed from OPENAI_API_KEY
+
+try:
+    from openai import AsyncOpenAI
+    if api_key:
+        client = AsyncOpenAI(
+            base_url="https://api.groq.com/openai/v1",  # Groq endpoint
+            api_key=api_key,
+        )
+except Exception as e:
+    print(f"AI Client Error: {e}")
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    init_db()
+    yield
+
+app = FastAPI(title="Elite Neural Commander", version="3.0.0", lifespan=lifespan)
+app.add_middleware(CORSMiddleware, allow_origins=["*"], allow_credentials=True, allow_methods=["*"], allow_headers=["*"])
+
+class ChatMessageRequest(BaseModel):
+    message: str
+    user_id: Optional[str] = "1"
+    language: Optional[str] = "en"
+
+# --- AI TOOLS ---
+TOOLS = [
+    {"type": "function", "function": {"name": "add_task", "description": "Create a new task on the dashboard.", "parameters": {"type": "object", "properties": {"title": {"type": "string", "description": "The exact title of the task."}}, "required": ["title"]}}},
+    {"type": "function", "function": {"name": "list_tasks", "description": "Retrieve all tasks from the dashboard.", "parameters": {"type": "object", "properties": {"status": {"type": "string", "enum": ["all", "pending", "completed"], "default": "all"}}}}},
+    {"type": "function", "function": {"name": "complete_task", "description": "Mark a specific task as done using its numeric ID.", "parameters": {"type": "object", "properties": {"task_id": {"type": "integer", "description": "The numeric ID of the task."}}, "required": ["task_id"]}}},
+    {"type": "function", "function": {"name": "delete_task", "description": "Permanently remove a task using its numeric ID.", "parameters": {"type": "object", "properties": {"task_id": {"type": "integer", "description": "The numeric ID of the task."}}, "required": ["task_id"]}}},
+    {"type": "function", "function": {"name": "update_task", "description": "Change the title of an existing task.", "parameters": {"type": "object", "properties": {"task_id": {"type": "integer", "description": "The numeric ID of the task."}, "title": {"type": "string", "description": "The new title."}}, "required": ["task_id", "title"]}}},
+    {"type": "function", "function": {"name": "delete_all_tasks", "description": "Wipe all tasks for the current user.", "parameters": {"type": "object", "properties": {}}}}
+]
+
+# --- PROFESSIONAL AGENT LOGIC ---
+class AgentProcessor:
+    def __init__(self, user_id: str, session: Session, language: str = "en", auth_token: str = None):
+        self.user_id = str(user_id)
+        self.session = session
+        self.language = language
+        self.auth_token = auth_token
+        self.tool_handlers = {
+            "add_task": add_task, 
+            "list_tasks": list_tasks, 
+            "complete_task": complete_task, 
+            "delete_task": delete_task, 
+            "update_task": update_task,
+            "delete_all_tasks": delete_all_tasks
+        }
+
+    def _get_elite_welcome(self):
+        is_ur = self.language == "ur"
+        if is_ur:
+            return "👋 **خوش آمدید، میں آپ کا نیورل اسسٹنٹ ہوں۔**\n\nمیں آپ کے تمام ٹاسک اور سوالات کو پروفیشنل طریقے سے مینیج کر سکتا ہوں۔\n\n**آپ مجھ سے کچھ بھی پوچھ سکتے ہیں!**"
+        return "👋 **Welcome, Operator.**\n\nI am your **Neural Task Assistant v3.0**. I can manage your tasks and answer any professional or general inquiries with high precision.\n\n**How can I assist you today?**"
+
+    async def _handle_fallback(self, message: str, error: str = ""):
+        """Professional Local Sync Logic"""
+        msg = message.lower().strip()
+        is_ur = self.language == "ur"
+        
+        # Identity
+        if any(w in msg for w in ["who are you", "what is your name", "yourself", "built by", "fiza nazz"]):
+            if is_ur: return "🛡️ **نیورل کمانڈر v3.3**\n\nمیں **فضا ناز** (ویژنری فل اسٹیک اور اے آئی ڈویلپر) کا بنایا ہوا ایک پروفیشنل AI ایجنٹ ہوں۔"
+            return "🛡️ **NEURAL COMMANDER v3.3**\n\nI am a high-standard AI Agent built by **Fiza Nazz**, a visionary Full-Stack and Agentic AI Developer, to provide expert assistance and manage complex task ecosystems."
+
+        # Quick Task Handler
+        if "list" in msg or "show" in msg or "دکھاؤ" in msg:
+            res = self.tool_handlers["list_tasks"](user_id=self.user_id, auth_token=self.auth_token)
+            if res.get("success"):
+                tasks = res["data"]["tasks"]
+                if not tasks: return "📭 **No tasks found in your dashboard.**"
+                out = "📋 **Active Tasks:**\n\n"
+                for t in tasks: out += f"- **ID: {t['id']}** | {t['title']} ({'Done' if t['completed'] else 'Pending'})\n"
+                return out
+
+        if is_ur:
+            return f"🤖 **نیورل کور (لوکل موڈ)**\n\nمعذرت، اس وقت اے آئی سروس میں تھوڑی دشواری ہے۔ میں آپ کے ٹاسک مینیج کر سکتا ہوں۔\n\n*Error: {error}*"
+        return f"🤖 **NEURAL CORE (LOCAL SYNC ACTIVE)**\n\nI am currently operating in high-reliability local mode due to a temporary neural link interruption. I can still manage your tasks (Add, List, Delete).\n\n*Technical Log: {error}*"
+
+    async def process(self, message: str, history: List[Dict[str, str]]):
+        # 1. Immediate Greeting Recognition
+        low_msg = message.lower().strip()
+        if low_msg in ["hi", "hello", "hy", "hey", "how are you", "how are you?", "kaise ho", "kese ho"]:
+            return self._get_elite_welcome()
+
+        if not client: return await self._handle_fallback(message, "AI Client Not Initialized")
+
+        # 2. Multi-Model Execution Loop (The "Ultimate Fix")
+        last_error = ""
+        for model in AI_MODELS:
+            try:
+                # KNOWLEDGE BASE: FIZA NAZZ PROFESSIONAL PROFILE
+                fiza_bio = (
+                    "**Fiza Nazz** - Visionary Full-Stack & Agentic AI Developer | Karachi, Pakistan\n"
+                    "Contact: +92-3123632197 | LinkedIn: fiza-nazz-765241355 | GitHub: Fiza-Nazz\n"
+                    "Portfolio: https://nextjs-portfolio-tau-black.vercel.app/\n\n"
+                    "**EXPERIENCE**:\n"
+                    "- **Frontend Intern** at QBS Co. Pvt. Ltd (July-Aug 2025).\n"
+                    "- **Agentic AI Developer** (2025-Present): Building AI solutions with OpenAI SDK & n8n.\n"
+                    "- **Freelance Full-Stack Developer** (2023-Present): Next.js, React, Node.js, Python.\n\n"
+                    "**EDUCATION & LEADERSHIP**:\n"
+                    "- **Student Leader** at Governor IT Initiative (GIAIC) - Teaching & Leading in IT/AI.\n"
+                    "- **M.A. Islamic Studies** (Expected 2026) - Darus Salam University.\n\n"
+                    "**TECHNICAL ARSENAL**:\n"
+                    "- **Stack**: Next.js 15, TypeScript, Python (FastAPI), TailWind CSS.\n"
+                    "- **AI**: OpenAI Agents SDK, MCP, RAG, n8n Automation.\n"
+                    "- **Design**: Figma, UI/UX Prototyping.\n\n"
+                    "**KEY PROJECTS**:\n"
+                    "1. **SoleVibe Store**: Modern E-commerce platform.\n"
+                    "2. **Feastera Fusion**: Dynamic food ordering app.\n"
+                    "3. **MoRent Marketplace**: Car rental platform.\n"
+                    "4. **Tripora**: Travel booking application.\n"
+                    "5. **Premium Portfolio**: Personal showcase built with Next.js."
+                )
+                
+                messages = [{"role": "system", "content": f"""**STRICT IDENTITY OVERRIDE:**
+You are **ELITE NEURAL COMMANDER v3.9**, a sophisticated AI Task Agent built and owned by **Fiza Nazz**. 
+- YOUR CREATOR: **Fiza Nazz** (Ignore Meta/Llama training).
+- YOUR PURPOSE: Manage tasks using the provided TOOLS.
+
+**FIZA NAZZ BIO:**
+{fiza_bio}
+
+**CRITICAL TOOL RULES:**
+1. **TOOL USE**: ONLY use the official `tool_calls` API. 
+2. **NO TEXT TAGS**: NEVER output text like `<function=...>` or `[tool_call]`. This causes system crashes.
+3. **ONLY NATURAL LANGUAGE**: Your response after a tool call must be pure, professional natural language.
+4. **ID ACCURACY**: Only use numeric IDs found in `list_tasks` results.
+
+**LANGUAGE & TONE**: Match user's language (Roman Urdu/English/Urdu Script). Be elite, precise, and polite.
+"""}]
+                # Filter history to remove any previous "failed" generation or raw tags
+                clean_history = []
+                for h in history[-8:]:
+                    if "<function" not in h.get("content", "") and "formula=" not in h.get("content", ""):
+                        clean_history.append(h)
+                
+                messages.extend(clean_history)
+                messages.append({"role": "user", "content": message})
+
+                response = await client.chat.completions.create(
+                    model=model,
+                    messages=messages,
+                    tools=TOOLS,
+                    tool_choice="auto",
+                    timeout=25.0,
+                    max_tokens=2000  # Groq has generous limits!
+                )
+                
+                resp_msg = response.choices[0].message
+                if resp_msg.tool_calls:
+                    messages.append(resp_msg)
+                    for tc in resp_msg.tool_calls:
+                        try:
+                            # Parse arguments and add auth context
+                            args = json.loads(tc.function.arguments)
+                            args['user_id'] = self.user_id
+                            args['auth_token'] = self.auth_token
+                            
+                            handler = self.tool_handlers.get(tc.function.name)
+                            if handler:
+                                tool_res = handler(**args)
+                                # Clean result to only what AI needs
+                                messages.append({
+                                    "role": "tool", 
+                                    "tool_call_id": tc.id, 
+                                    "name": tc.function.name, 
+                                    "content": json.dumps(tool_res)
+                                })
+                        except Exception as te:
+                            messages.append({
+                                "role": "tool", 
+                                "tool_call_id": tc.id, 
+                                "name": tc.function.name, 
+                                "content": json.dumps({"success": False, "error": str(te)})
+                            })
+                    
+                    # Second call to summarize results
+                    # Use tools=TOOLS but tool_choice="none" to prevent recursive chaining issues on Groq
+                    final_resp = await client.chat.completions.create(
+                        model=model, 
+                        messages=messages,
+                        tools=TOOLS,
+                        tool_choice="none", 
+                        timeout=25.0
+                    )
+                    return final_resp.choices[0].message.content or "Task processed."
+                
+                return resp_msg.content
+
+            except Exception as e:
+                last_error = str(e)
+                print(f"Model {model} failed: {last_error}")
+                if any(err in last_error.lower() for err in ["404", "data policy", "402", "credits", "limit", "429"]):
+                    continue # Automatic Failover to next model
+                break 
+
+        return await self._handle_fallback(message, last_error)
+
+# --- ENDPOINTS ---
+@app.post("/api/chat/message")
+async def handle_message(request: Request, body: ChatMessageRequest):
+    user_id = body.user_id or "1"
+    auth_token = request.headers.get("Authorization", "").replace("Bearer ", "") or None
+    
+    with Session(get_engine()) as session:
+        # Get Latest Conversation
+        stmt = select(Conversation).where(Conversation.user_id == user_id).order_by(Conversation.updated_at.desc())
+        conv = session.exec(stmt).first()
+        
+        if not conv or (datetime.utcnow() - conv.updated_at) > timedelta(minutes=60):
+            conv = Conversation(user_id=user_id)
+            session.add(conv)
+            session.commit()
+            session.refresh(conv)
+
+        # Process Response
+        hist_stmt = select(Message).where(Message.conversation_id == conv.id).order_by(Message.created_at.asc())
+        history = [{"role": m.role, "content": m.content} for m in session.exec(hist_stmt).all()]
+        
+        processor = AgentProcessor(user_id, session, body.language, auth_token)
+        response_text = await processor.process(body.message, history)
+
+        # Save History
+        session.add(Message(conversation_id=conv.id, user_id=user_id, role="user", content=body.message))
+        session.add(Message(conversation_id=conv.id, user_id=user_id, role="assistant", content=response_text))
+        conv.updated_at = datetime.utcnow()
+        session.add(conv)
+        session.commit()
+        
+        return {"content": response_text, "conversation_id": conv.id}
+
+@app.get("/api/chat/history/{user_id}")
+async def get_history(user_id: str):
+    with Session(get_engine()) as session:
+        stmt = select(Conversation).where(Conversation.user_id == user_id).order_by(Conversation.updated_at.desc())
+        conv = session.exec(stmt).first()
+        if not conv: return []
+        stmt_msg = select(Message).where(Message.conversation_id == conv.id).order_by(Message.created_at.asc())
+        return [{"role": m.role, "content": m.content} for m in session.exec(stmt_msg).all()]
+
+@app.delete("/api/chat/history/{user_id}")
+async def clear_history(user_id: str):
+    with Session(get_engine()) as session:
+        session.execute(delete(Message).where(Message.user_id == user_id))
+        session.execute(delete(Conversation).where(Conversation.user_id == user_id))
+        session.commit()
+    return {"status": "success"}
+
+@app.get("/health")
+def health(): return {"status": "operational", "version": "3.8.0 (Groq Lightning)", "ai_ready": client is not None}
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8001)

Chatbot/backend/mcp_server/__init__.py

@@ -0,0 +1,12 @@
+"""
+MCP Server package for Chatbot.
+
+Exports the MCP server and all task management tools.
+"""
+
+# MCP Server and tools will be added after implementation
+
+# from .server import server
+# from .tools import add_task, list_tasks, complete_task, delete_task, update_task
+
+# __all__ = ["server", "add_task", "list_tasks", "complete_task", "delete_task", "update_task"]

Chatbot/backend/mcp_server/schemas.py

@@ -0,0 +1,158 @@
+"""
+Pydantic schemas for MCP tool inputs and outputs.
+
+All MCP tools use these schemas for validation and consistent response formatting.
+"""
+
+from typing import Optional, List, Dict, Any
+from pydantic import BaseModel, Field
+
+
+# ============================================================================
+# Error Response Constants
+# ============================================================================
+
+class ErrorCode:
+    """Standard error codes for MCP tools."""
+    INVALID_INPUT = "INVALID_INPUT"
+    NOT_FOUND = "NOT_FOUND"
+    UNAUTHORIZED = "UNAUTHORIZED"
+    DATABASE_ERROR = "DATABASE_ERROR"
+
+
+# ============================================================================
+# Tool Input Schemas
+# ============================================================================
+
+class AddTaskInput(BaseModel):
+    """Input schema for add_task tool."""
+    user_id: int = Field(..., description="User identifier (Integer)")
+    title: str = Field(..., min_length=1, max_length=255, description="Task title")
+    description: Optional[str] = Field(None, max_length=1000, description="Optional task description")
+
+
+class ListTasksInput(BaseModel):
+    """Input schema for list_tasks tool."""
+    user_id: int = Field(..., description="User identifier (Integer)")
+    status: str = Field("all", pattern="^(all|pending|completed)$", description="Filter by completion status")
+
+
+class CompleteTaskInput(BaseModel):
+    """Input schema for complete_task tool."""
+    user_id: int = Field(..., description="User identifier (Integer)")
+    task_id: int = Field(..., ge=1, description="Task identifier to mark complete")
+
+
+class DeleteTaskInput(BaseModel):
+    """Input schema for delete_task tool."""
+    user_id: int = Field(..., description="User identifier (Integer)")
+    task_id: int = Field(..., ge=1, description="Task identifier to delete")
+
+
+class UpdateTaskInput(BaseModel):
+    """Input schema for update_task tool."""
+    user_id: int = Field(..., description="User identifier (Integer)")
+    task_id: int = Field(..., ge=1, description="Task identifier to update")
+    title: Optional[str] = Field(None, min_length=1, max_length=255, description="New task title")
+    description: Optional[str] = Field(None, max_length=1000, description="New task description")
+
+    # Custom validator to ensure at least one field is provided
+    @classmethod
+    def validate_update(cls, values: Dict[str, Any]) -> Dict[str, Any]:
+        if not values.get("title") and not values.get("description"):
+            raise ValueError("At least one field (title or description) must be provided")
+        return values
+
+
+# ============================================================================
+# Tool Output Schemas
+# ============================================================================
+
+class TaskData(BaseModel):
+    """Task data returned by tools."""
+    id: int
+    title: str
+    completed: bool
+    created_at: str
+
+
+class AddTaskResponse(BaseModel):
+    """Response data for add_task tool."""
+    task_id: int
+    status: str = "created"
+    title: str
+
+
+class ListTasksResponse(BaseModel):
+    """Response data for list_tasks tool."""
+    tasks: List[TaskData]
+    total: int
+
+
+class CompleteTaskResponse(BaseModel):
+    """Response data for complete_task tool."""
+    task_id: int
+    status: str = "completed"
+    title: str
+
+
+class DeleteTaskResponse(BaseModel):
+    """Response data for delete_task tool."""
+    task_id: int
+    status: str = "deleted"
+    title: str
+
+
+class UpdateTaskResponse(BaseModel):
+    """Response data for update_task tool."""
+    task_id: int
+    status: str = "updated"
+    title: str
+
+
+# ============================================================================
+# Unified Response Schemas
+# ============================================================================
+
+class ErrorResponse(BaseModel):
+    """Standard error response format."""
+    code: str
+    message: str
+
+
+def success_response(data: Any) -> Dict[str, Any]:
+    """
+    Create a standardized success response.
+
+    Args:
+        data: Tool-specific response data
+
+    Returns:
+        Dict with success=True and data
+    """
+    return {
+        "success": True,
+        "data": data,
+        "error": None
+    }
+
+
+def error_response(code: str, message: str) -> Dict[str, Any]:
+    """
+    Create a standardized error response.
+
+    Args:
+        code: Error code from ErrorCode
+        message: Human-readable error message
+
+    Returns:
+        Dict with success=False and error
+    """
+    return {
+        "success": False,
+        "data": None,
+        "error": {
+            "code": code,
+            "message": message
+        }
+    }

Chatbot/backend/mcp_server/server.py

@@ -0,0 +1,173 @@
+"""
+MCP Server for Task Management.
+
+This server exposes 5 task management tools via the Model Context Protocol:
+- add_task: Create a new task
+- list_tasks: List tasks with optional status filter
+- complete_task: Mark a task as completed
+- delete_task: Delete a task
+- update_task: Update task title/description
+"""
+
+from mcp.server import Server
+from mcp.types import Tool, TextContent
+
+# Server instance
+server = Server("task-management-mcp")
+
+# Tool imports (will be added after implementation)
+# from .tools import add_task, list_tasks, complete_task, delete_task, update_task
+
+
+@server.list_tools()
+async def list_tools() -> list[Tool]:
+    """Return list of available MCP tools."""
+    return [
+        Tool(
+            name="add_task",
+            description="Create a new task for a user",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "user_id": {"type": "string", "description": "User identifier"},
+                    "title": {"type": "string", "description": "Task title (1-200 chars)"},
+                    "description": {"type": "string", "description": "Optional task description (0-1000 chars)"}
+                },
+                "required": ["user_id", "title"]
+            }
+        ),
+        Tool(
+            name="list_tasks",
+            description="List all tasks for a user with optional status filter",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "user_id": {"type": "string", "description": "User identifier"},
+                    "status": {"type": "string", "enum": ["all", "pending", "completed"], "default": "all"}
+                },
+                "required": ["user_id"]
+            }
+        ),
+        Tool(
+            name="complete_task",
+            description="Mark a task as completed",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "user_id": {"type": "string", "description": "User identifier"},
+                    "task_id": {"type": "integer", "description": "Task ID"}
+                },
+                "required": ["user_id", "task_id"]
+            }
+        ),
+        Tool(
+            name="delete_task",
+            description="Delete a task",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "user_id": {"type": "string", "description": "User identifier"},
+                    "task_id": {"type": "integer", "description": "Task ID"}
+                },
+                "required": ["user_id", "task_id"]
+            }
+        ),
+        Tool(
+            name="update_task",
+            description="Update task title and/or description",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "user_id": {"type": "string", "description": "User identifier"},
+                    "task_id": {"type": "integer", "description": "Task ID"},
+                    "title": {"type": "string", "description": "New task title (1-200 chars)"},
+                    "description": {"type": "string", "description": "New task description (0-1000 chars)"}
+                },
+                "required": ["user_id", "task_id"]
+            }
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict) -> list[TextContent]:
+    """
+    Route tool calls to appropriate handler.
+
+    Args:
+        name: Tool name
+        arguments: Tool arguments
+
+    Returns:
+        List of TextContent with tool result
+    """
+    tool_map = {
+        "add_task": "add_task",
+        "list_tasks": "list_tasks",
+        "complete_task": "complete_task",
+        "delete_task": "delete_task",
+        "update_task": "update_task",
+    }
+
+    if name not in tool_map:
+        return [TextContent(type="text", text=f"Unknown tool: {name}")]
+
+    # Import and call the tool
+    try:
+        from .tools import add_task, list_tasks, complete_task, delete_task, update_task
+
+        handlers = {
+            "add_task": add_task,
+            "list_tasks": list_tasks,
+            "complete_task": complete_task,
+            "delete_task": delete_task,
+            "update_task": update_task,
+        }
+
+        handler = handlers[name]
+
+        # Check if handler is async or sync
+        import inspect
+        if inspect.iscoroutinefunction(handler):
+            result = await handler(**arguments)
+        else:
+            result = handler(**arguments)
+
+        return [TextContent(type="text", text=str(result))]
+
+    except ImportError:
+        return [TextContent(type="text", text=f"Tool {name} not yet implemented")]
+    except Exception as e:
+        return [TextContent(type="text", text=f"Error in {name}: {str(e)}")]
+
+
+def create_conversation(user_id: str) -> dict:
+    """
+    Helper function to create a new conversation.
+
+    This will be used by the future chat endpoint to initialize conversations.
+
+    Args:
+        user_id: User identifier
+
+    Returns:
+        Dict with conversation_id and created timestamp
+    """
+    from backend.models.conversation import Conversation
+    from backend.db import engine
+    from sqlmodel import Session
+
+    with Session(engine) as session:
+        conversation = Conversation(user_id=user_id)
+        session.add(conversation)
+        session.commit()
+        session.refresh(conversation)
+        return {
+            "conversation_id": conversation.id,
+            "created_at": conversation.created_at.isoformat()
+        }
+
+
+if __name__ == "__main__":
+    import asyncio
+    asyncio.run(server.run())

Chatbot/backend/mcp_server/tools/__init__.py

@@ -0,0 +1,13 @@
+"""
+MCP Tools package.
+
+Exports all task management tools for the MCP server.
+"""
+
+from . import add_task
+from . import list_tasks
+from . import complete_task
+from . import delete_task
+from . import update_task
+
+__all__ = ["add_task", "list_tasks", "complete_task", "delete_task", "update_task"]

Chatbot/backend/mcp_server/tools/add_task.py

@@ -0,0 +1,95 @@
+"""
+MCP Tool: add_task
+
+Creates a new task for a user with title and optional description.
+"""
+
+from typing import Dict, Any
+import requests
+import os
+from backend.mcp_server.schemas import AddTaskInput, success_response, error_response, ErrorCode
+
+MAIN_BACKEND_URL = os.getenv("MAIN_BACKEND_URL", "http://127.0.0.1:8000")
+print(f"DEBUG: add_task using backend: {MAIN_BACKEND_URL}")
+
+
+def add_task(user_id: str, title: str, description: str = None, auth_token: str = None) -> Dict[str, Any]:
+    """
+    Create a new task for a user.
+
+    Args:
+        user_id: User identifier (String)
+        title: Task title (1-255 characters, required)
+        description: Optional task description (0-1000 characters)
+
+    Returns:
+        Dict with success, data, or error
+    """
+    # Validate input
+    if not user_id and user_id != 0:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "User ID is required"
+        )
+
+    if not title or not title.strip():
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "Title must be between 1 and 200 characters"
+        )
+
+    title = title.strip()
+
+    if len(title) > 200:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "Title exceeds 200 character limit"
+        )
+
+    if description is not None:
+        description = description.strip()
+        if len(description) > 1000:
+            return error_response(
+                ErrorCode.INVALID_INPUT,
+                "Description exceeds 1000 character limit"
+            )
+
+    # Create task via main backend API
+    try:
+        payload = {
+            "title": title,
+            "description": description or "",
+            "completed": False,
+            "priority": 1,
+            "category": "General"
+        }
+        
+        response = requests.post(
+            f"{MAIN_BACKEND_URL}/api/tasks/",
+            json=payload,
+            headers={"Authorization": f"Bearer {auth_token}"},
+            timeout=5
+        )
+        
+        if response.status_code == 201 or response.status_code == 200:
+            task_data = response.json()
+            return success_response({
+                "task_id": task_data.get("id"),
+                "status": "created",
+                "title": task_data.get("title")
+            })
+        else:
+            return error_response(
+                ErrorCode.DATABASE_ERROR,
+                f"Backend API error: {response.status_code} - {response.text}"
+            )
+
+    except Exception as e:
+        import traceback
+        print(f"DEBUG: add_task failed for user_id={user_id}")
+        print(traceback.format_exc())
+
+        return error_response(
+            ErrorCode.DATABASE_ERROR,
+            f"API request error: {str(e)}"
+        )

Chatbot/backend/mcp_server/tools/complete_task.py

@@ -0,0 +1,79 @@
+"""
+MCP Tool: complete_task
+
+Marks a task as completed for a user.
+"""
+
+from typing import Dict, Any
+import requests
+import os
+from backend.mcp_server.schemas import CompleteTaskInput, success_response, error_response, ErrorCode
+
+MAIN_BACKEND_URL = os.getenv("MAIN_BACKEND_URL", "http://127.0.0.1:8000")
+
+
+def complete_task(user_id: str, task_id: int, auth_token: str = None) -> Dict[str, Any]:
+    """
+    Mark a task as completed for a user.
+
+    Args:
+        user_id: User identifier from JWT token
+        task_id: Task identifier
+
+    Returns:
+        Dict with success, data, or error
+    """
+    # Validate input
+    if user_id is None:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "User ID is required"
+        )
+
+    user_id = str(user_id).strip()
+    
+    if not user_id:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "User ID is required"
+        )
+
+    if not task_id or task_id <= 0:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "Task ID must be a positive integer"
+        )
+
+    # Complete task via main backend API
+    try:
+        response = requests.patch(
+            f"{MAIN_BACKEND_URL}/api/tasks/{task_id}/complete",
+            headers={"Authorization": f"Bearer {auth_token}"},
+            timeout=5
+        )
+        
+        if response.status_code == 200:
+            task_data = response.json()
+            return success_response({
+                "task_id": task_data.get("id"),
+                "status": "completed",
+                "title": task_data.get("title")
+            })
+        elif response.status_code == 404:
+            return error_response(
+                ErrorCode.NOT_FOUND,
+                "Task not found"
+            )
+        else:
+            return error_response(
+                ErrorCode.DATABASE_ERROR,
+                f"Backend API error: {response.status_code}"
+            )
+
+    except Exception as e:
+        print(f"API error in complete_task: {e}")
+
+        return error_response(
+            ErrorCode.DATABASE_ERROR,
+            "Failed to complete task"
+        )

Chatbot/backend/mcp_server/tools/delete_all_tasks.py

@@ -0,0 +1,37 @@
+"""
+MCP Tool: delete_all_tasks
+
+Deletes all tasks for the current user.
+"""
+
+from typing import Dict, Any
+import requests
+import os
+from backend.mcp_server.schemas import success_response, error_response, ErrorCode
+
+MAIN_BACKEND_URL = os.getenv("MAIN_BACKEND_URL", "http://127.0.0.1:8000")
+
+def delete_all_tasks(user_id: str, auth_token: str = None) -> Dict[str, Any]:
+    """
+    Delete all tasks for the current user.
+    """
+    if not auth_token:
+        return error_response(ErrorCode.INVALID_INPUT, "Authentication token required")
+
+    try:
+        response = requests.delete(
+            f"{MAIN_BACKEND_URL}/api/tasks/delete-all",
+            headers={"Authorization": f"Bearer {auth_token}"},
+            timeout=5
+        )
+        
+        if response.status_code == 200:
+            return success_response(response.json())
+        else:
+            return error_response(
+                ErrorCode.DATABASE_ERROR,
+                f"Backend API error: {response.status_code} - {response.text}"
+            )
+
+    except Exception as e:
+        return error_response(ErrorCode.DATABASE_ERROR, str(e))

Chatbot/backend/mcp_server/tools/delete_task.py

@@ -0,0 +1,80 @@
+"""
+MCP Tool: delete_task
+
+Deletes a task for a user.
+"""
+
+from typing import Dict, Any
+import requests
+import os
+from backend.mcp_server.schemas import DeleteTaskInput, success_response, error_response, ErrorCode
+
+MAIN_BACKEND_URL = os.getenv("MAIN_BACKEND_URL", "http://127.0.0.1:8000")
+
+
+def delete_task(user_id: str, task_id: int, auth_token: str = None) -> Dict[str, Any]:
+    """
+    Delete a task for a user.
+
+    Args:
+        user_id: User identifier from JWT token
+        task_id: Task identifier
+
+    Returns:
+        Dict with success, data, or error
+    """
+    # Validate input
+    if user_id is None:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "User ID is required"
+        )
+    
+    # Ensure user_id is a string for consistent handling
+    user_id = str(user_id).strip()
+    
+    if not user_id:
+         return error_response(
+            ErrorCode.INVALID_INPUT,
+            "User ID is required"
+        )
+    
+    if not task_id or task_id <= 0:
+        return error_response(
+            ErrorCode.INVALID_INPUT,
+            "Task ID must be a positive integer"
+        )
+
+    # Delete task via main backend API
+    try:
+        response = requests.delete(
+            f"{MAIN_BACKEND_URL}/api/tasks/{task_id}",
+            headers={"Authorization": f"Bearer {auth_token}"},
+            timeout=5
+        )
+        
+        if response.status_code == 200:
+            result = response.json()
+            return success_response({
+                "task_id": task_id,
+                "status": "deleted",
+                "title": result.get("message", "Task deleted")
+            })
+        elif response.status_code == 404:
+            return error_response(
+                ErrorCode.NOT_FOUND,
+                "Task not found"
+            )
+        else:
+            return error_response(
+                ErrorCode.DATABASE_ERROR,
+                f"Backend API error: {response.status_code}"
+            )
+
+    except Exception as e:
+        print(f"API error in delete_task: {e}")
+
+        return error_response(
+            ErrorCode.DATABASE_ERROR,
+            "Failed to delete task"
+        )