diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a4e68a8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,85 @@ +# Project Instructions + +Development standards and guidelines for Claude Code when working on this project. + +## Git Workflow + +**NEVER push directly to main.** All changes must go through pull requests. + +### Rules + +1. Always work on feature branches +2. Create pull requests using `gh pr create` +3. Wait for user approval before merging +4. No force pushes to main + +### Workflow + +```bash +# 1. Create feature branch +git checkout -b feat/my-feature + +# 2. Make changes and validate +just validate-branch + +# 3. Commit and push +git add +git commit -m "feat: description" +git push origin feat/my-feature + +# 4. Create PR +gh pr create --title "feat: Title" --body "Description" + +# 5. WAIT for user approval before merging +``` + +## Development Standards + +### Before Any Commit + +Run full validation: + +```bash +just validate-branch +``` + +This runs: +- `just format` - Code formatting (black, ruff) +- `just lint` - Linting with auto-fix +- `just type-check` - Type validation (mypy strict) +- `just test` - Tests with 80% coverage minimum + +### Test Naming Convention + +All tests must follow: `test____` + +Examples: +- `test__parse_config__returns_valid_settings` +- `test__api_call__raises_on_timeout` +- `test__logger_init__creates_json_processor_in_production` + +### Code Style + +- Python 3.12+ +- Type hints on all functions +- Pydantic for data validation +- structlog for logging +- 120 character line limit + +## Local Development + +```bash +just init # Set up environment +just run # Run main application +just test # Run test suite +just test-unit # Fast unit tests only +just validate-branch # Full validation (required before commits) +``` + +## Project Structure + +``` +src/ # Python source code +tests/ # Test suite (mirrors src/ structure) +.github/workflows/ # CI/CD pipelines +``` diff --git a/README.md b/README.md index a981669..25209d5 100644 --- a/README.md +++ b/README.md @@ -1,135 +1,117 @@ -# Python Agentic Template +# Autonomous Python Template > Describe what you want to build. Let agents build it. -Autonomous multi-agent Python project template. +A self-building Python ML/Data Science template powered by Claude Code. Clone, describe your project, and watch it come to life. -## Why This Template? +## Quick Start -**The Problem:** Starting AI/ML projects requires extensive setup—architecture decisions, project structure, testing patterns, CI/CD, logging, and more. Most developers copy-paste from old projects or spend days configuring from scratch. +### 1. Clone this template -**The Solution:** This template **bootstraps itself** into a complete, production-ready project through a multi-agent workflow. You describe your project in plain language; agents research, plan, and build it. +```bash +git clone https://github.com/ai-enhanced-engineer/aut-python-template.git my-project +cd my-project +``` -## How It Works +### 2. Set up environment +```bash +just init ``` -┌─────────────────────────────────────────────────────────────────┐ -│ YOU: Fill context/PRODUCT.md + context/ENGINEERING.md │ -│ (Describe what you're building and technical preferences) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ PHASE 0: Agent Discovery │ -│ Claude Code finds available specialists and maps │ -│ them to roles (research, architecture, implementation,│ -│ review) │ -└─────────────────────────────────────────────────────────────────┘ - ↓ -┌─────────────────────────────────────────────────────────────────┐ -│ PHASE 1: Research │ -│ Expands your seeds into full PRD │ -│ Researches best practices, grades evidence │ -│ → context/PRD.md, context/RESEARCH_SYNTHESIS.md │ -└─────────────────────────────────────────────────────────────────┘ - ↓ [User Approval] -┌─────────────────────────────────────────────────────────────────┐ -│ PHASE 2: Architecture │ -│ Creates ADRs and project plan │ -│ Defines MVP scope with MoSCoW prioritization │ -│ → ADR.md, context/PROJECT_PLAN.md │ -└─────────────────────────────────────────────────────────────────┘ - ↓ [User Approval] -┌─────────────────────────────────────────────────────────────────┐ -│ PHASE 3: MVP Implementation │ -│ Builds must-have features with tests │ -│ Per deliverable: IMPLEMENT → REVIEW → FIX → PASS │ -│ Review enforces 80% coverage, test quality │ -│ → Working code in src/ │ -└─────────────────────────────────────────────────────────────────┘ - ↓ [User Approval] -┌─────────────────────────────────────────────────────────────────┐ -│ PHASE 4: Feature Enhancement │ -│ Adds features from roadmap (same validation loop) │ -│ Each feature: IMPLEMENT → REVIEW → FIX → User Approval│ -└─────────────────────────────────────────────────────────────────┘ + +### 3. Start Claude Code + +```bash +claude ``` -**Human-in-the-loop**: You approve each phase before continuing. No runaway automation. +### 4. Describe your project -## Quick Start +``` +> I want to build a RAG system for legal documents +``` -1. **Create your repository**: Click "Use this template" on GitHub -2. **Set up environment**: `just init` -3. **Fill out your seeds**: Edit `context/PRODUCT.md` and `context/ENGINEERING.md` -4. **Start brewing**: In Claude Code, say `"Run the project initialization workflow"` +That's it. Describe what you want; agents help you build it. -### Filling Out Seeds +## Example Session -| File | What to Include | -|------|-----------------| -| `context/PRODUCT.md` | What you're building, for whom, why, success criteria | -| `context/ENGINEERING.md` | Technical preferences, constraints, architecture ideas | +``` +You: I want to build a fraud detection API -**Tips for better results**: -- Be specific about the problem: "Users waste 2 hours/day on X" > "Users have problems" -- Define success measurably: "50% reduction in Y" > "Improve Y" -- State constraints clearly: "Must run on GCP" > "Cloud deployment" +Claude: I'll help you build a fraud detection API. Let me understand your requirements: + - What data sources will you use? (transactions, user behavior, etc.) + - Any specific ML approach preference? (rule-based, XGBoost, neural network) + - What's your target latency for predictions? -See `workflows/PROJECT_INIT_WORKFLOW.md` for the complete workflow specification. +You: Transaction data from a PostgreSQL database. XGBoost for now, we can upgrade later. + Need sub-100ms latency. -## What You Get +Claude: Great, let me set up the project structure: + 1. Creating data pipeline for PostgreSQL ingestion + 2. Setting up XGBoost model with feature engineering + 3. Building FastAPI endpoint with async handlers + 4. Adding monitoring and logging -Beyond the autonomous workflow, this template provides a **production-ready foundation**: + [Creates files, writes tests, validates...] -### Modern Python Tooling -- Python 3.12+, FastAPI, Pydantic -- Type hints throughout -- uv for fast dependency management +You: Add a batch prediction endpoint too + +Claude: Adding batch prediction endpoint with: + - CSV upload support + - Background processing with status tracking + - Results stored in PostgreSQL + + [Implements, tests, validates...] +``` + +## What's Included + +This template comes with production-ready infrastructure: ### Production Logging -- Structured JSON logging with structlog + +- Structured JSON logging with [structlog](https://www.structlog.org/) - Correlation ID tracking across requests - Dual-mode: human-readable (dev) / JSON (prod) -### Development Automation -- Pre-configured linting (Ruff), formatting (Black), type checking (mypy) +### Testing Infrastructure + +- pytest with markers (unit, functional, integration) +- 80% coverage requirement - Pre-commit hooks for quality gates -- `just validate-branch` runs all checks -### Testing Patterns -- Unit, functional, and integration test structure -- pytest with markers for test organization -- 21+ logging system tests included as examples +### CI/CD Pipeline -### CI/CD Ready - GitHub Actions workflows -- Semantic versioning -- Docker-ready structure +- Semantic versioning with auto-release +- Format → Lint → Type-check → Test pipeline + +### Modern Python Tooling + +- Python 3.12+ +- Type hints throughout +- Pydantic for data validation +- uv for fast dependency management +- Ruff + Black for formatting/linting +- mypy (strict mode) for type checking ## Project Structure ``` my-project/ -├── context/ # Project seeds + workflow outputs -│ ├── PRODUCT.md # Your product requirements (seed) -│ ├── ENGINEERING.md # Your technical preferences (seed) -│ ├── PRD.md # Expanded PRD (generated) -│ ├── RESEARCH_SYNTHESIS.md # Research findings (generated) -│ └── PROJECT_PLAN.md # MVP scope + roadmap (generated) -├── workflows/ # Autonomous workflow system -│ ├── PROJECT_INIT_WORKFLOW.md # Complete workflow specification -│ └── templates/ # Output format contracts -├── src/ # Your service code +├── src/ # Python source code │ ├── __init__.py -│ ├── main.py # Entry point with logging demo │ └── logging.py # Production logging system ├── tests/ # Test suite -│ ├── test_main.py -│ └── test_logging.py # 21+ logging tests -├── research/ # Notebooks and experiments -├── ADR.md # Architecture decisions (generated) -├── justfile # All automation commands -└── pyproject.toml # Project configuration +│ └── test_logging.py # 21+ logging tests as examples +├── .claude/ # Claude Code settings +├── .github/workflows/ # CI/CD pipelines +│ └── ci.yml +├── CLAUDE.md # Development standards +├── pyproject.toml # Project configuration +├── justfile # Automation commands +├── ADR.md # Architecture decisions +└── .pre-commit-config.yaml # Git hooks ``` ## Development Commands @@ -164,31 +146,30 @@ This template embodies the principle that **production AI requires engineering d - **Reliability over novelty**: Production systems must work consistently, not just impressively - **Plan for failure**: Every external call needs error handling; every assumption needs validation -The autonomous workflow ensures these patterns are built in from the start, not bolted on later. - ## Who Should Use This -### Teams Starting AI/ML Projects -Stop reinventing infrastructure. Describe your project and let agents build a production-ready foundation. +### Teams Starting ML/Data Projects + +Stop reinventing infrastructure. Describe your project and get a production-ready foundation. -### Senior Engineers New to AI -Get the safety rails you're accustomed to in production systems while learning AI concepts. +### Senior Engineers New to ML + +Get the safety rails you're accustomed to in production systems while learning ML concepts. ### Technical Leaders + Give your team a consistent, production-ready starting point that embodies engineering best practices. ## Learn More -### This Template -- `workflows/PROJECT_INIT_WORKFLOW.md` - Complete workflow specification -- `workflows/templates/` - Output format examples - ### Production AI Engineering + - [A Production-First Approach to AI Engineering](https://aienhancedengineer.substack.com/p/a-production-first-approach-to-ai) - [Google's Rules for ML](https://developers.google.com/machine-learning/guides/rules-of-ml) - [Hidden Technical Debt in ML Systems](https://papers.nips.cc/paper/5656-hidden-technical-debt-in-machine-learning-systems.pdf) ### Technologies + - [FastAPI](https://fastapi.tiangolo.com/) - Modern Python web framework - [Pydantic](https://docs.pydantic.dev/) - Data validation - [structlog](https://www.structlog.org/) - Structured logging @@ -197,6 +178,7 @@ Give your team a consistent, production-ready starting point that embodies engin ## Contributing When contributing, prioritize: + 1. **Reliability over features** 2. **Simplicity over cleverness** 3. **Documentation over assumptions** diff --git a/pyproject.toml b/pyproject.toml index 848df66..0b4c503 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,10 @@ [project] -name = "python-agentic-template" +# TODO: Change to your project name +name = "aut-python-template" version = "0.5.0" -description = "Autonomous multi-agent Python project template - Describe what you want, let agents build it" +# TODO: Update project description +description = "Autonomous Python ML/Data Science template - Describe your project, let agents build it" +# TODO: Update author information authors = [{name="Leopoldo Garcia Vargas", email="lk13.dev@gmail.com"}] requires-python = ">=3.12" license = {text = "Apache-2.0"} diff --git a/workflows/PROJECT_INIT_WORKFLOW.md b/workflows/PROJECT_INIT_WORKFLOW.md deleted file mode 100644 index 7f0590e..0000000 --- a/workflows/PROJECT_INIT_WORKFLOW.md +++ /dev/null @@ -1,628 +0,0 @@ -# Project Initialization Workflow - -> **Runtime**: Claude Code -> **Recommended Orchestrator**: Opus (for multi-agent coordination) -> **Sub-agents**: Sonnet or Haiku (for specialized tasks) - -Transform this template into a project-specific system through agent-orchestrated phases with user approval gates. - -## Overview - -| Aspect | Description | -|--------|-------------| -| **Purpose** | Transform template into project-specific system | -| **Pattern** | Sequential agent orchestration with incremental complexity | -| **Approval** | User approval required at each phase gate | - -## Agent Role Definitions - -This workflow uses **abstract roles** instead of specific agent names for portability. During Phase 0, Claude Code discovers available specialists and maps them to these roles. - -| Role | Capability | Phase | Example Agents | -|------|------------|-------|----------------| -| `research` | Web research, evidence synthesis, context gathering | 1 | context-engineer, researcher | -| `architecture` | ADRs, system design, MVP scoping | 2 | project-architect, ml-systems-architect | -| `implementation` | Code writing, testing, domain expertise | 3-4 | ai-engineer, backend-engineer, data-engineer, agentic-engineer | -| `review` | Test enforcement, code quality auditing | 3-4 | python-code-quality-auditor | - -**Role Matching Keywords**: - -| Role | Keywords in Agent Description | -|------|-------------------------------| -| research | research, context, synthesis, investigation, analysis | -| architecture | architect, design, planning, ADR, system, infrastructure | -| implementation | engineer, developer, implement, code, build | -| review | review, audit, quality, test, enforce, validate, check, gate | - -**Note**: The `implementation` role supports **multiple specialists** - different agents can be assigned to different features based on domain expertise. - ---- - -## Discovered Agents - -*This section is updated in place during Phase 0.* - -| Role | Selected Agent(s) | Source | Status | -|------|-------------------|--------|--------| -| research | [pending discovery] | - | ⏳ | -| architecture | [pending discovery] | - | ⏳ | -| implementation | [pending discovery] | - | ⏳ | -| review | [pending discovery] | - | ⏳ | - ---- - -## Phase 0: Agent Discovery - -Before starting the workflow, Claude Code discovers available specialists and maps them to roles. - -**Actions**: -1. Scan for agents at: - - Project level: `.claude/agents/*.md` - - User level: `~/.claude/agents/*.md` -2. Read agent descriptions and match to roles using keywords -3. Present candidates to user for approval -4. Update "Discovered Agents" section above with selections - -**User Approval**: - -Claude Code presents discovered agents: -``` -Found specialists for this workflow: - -research: context-engineer (user) - "Web research and evidence synthesis" -architecture: project-architect (user) - "ADRs and system design" -implementation: ai-engineer (user) - "RAG and LLM integration" - backend-engineer (user) - "APIs and databases" -review: python-code-quality-auditor (user) - "Code quality and test enforcement" - -Approve these selections? [Y/n/modify] -``` - -**If No Matches Found**: - -``` -⚠️ WARNING: No specialist found for role [research]. - Workflow will proceed with generalist Claude Code. - Consider creating a specialist agent for better results. -``` - -**After Discovery**: - -Update the "Discovered Agents" table above, then proceed to Prerequisites. - ---- - -## Inter-Phase Communication - -Templates in `workflows/templates/` serve as **structured contracts** between phases: - -| Template | Output Location | Produced By | Consumed By | -|----------|-----------------|-------------|-------------| -| `TEMPLATE-PRD.md` | `context/PRD.md` | `research` role (Phase 1) | `architecture` role (Phase 2) | -| `TEMPLATE-ADR.md` | `ADR.md` (root) | `architecture` role (Phase 2) | `implementation` role (Phase 3) | -| `TEMPLATE-PROJECT-PLAN.md` | `context/PROJECT_PLAN.md` | `architecture` role (Phase 2) | `implementation` role (Phase 3-4) | - -Templates remain in `workflows/templates/` as reusable scaffolds. - -**Why templates matter:** -- **Predictable handoffs**: Each phase knows exactly what format to expect -- **Agent independence**: Agents don't need to negotiate formats -- **Human readability**: User can review outputs at each approval gate - ---- - -## Prerequisites - -Before running this workflow: - -1. **Fill out seed documents** in `context/`: - - `context/PRODUCT.md` - Product/business perspective (what & why) - - `context/ENGINEERING.md` - Technical perspective (how & constraints) - -2. **Run Phase 0**: Discover and confirm available specialists (or accept generalist fallback) - -3. **Support files** in `workflows/`: - - Templates for agent outputs - - Agent specifications - ---- - -## Phase 1: Context Research - -**Role**: `research` -**Agent**: *[See Discovered Agents table]* - -**Input**: -- `context/PRODUCT.md` - User-provided product seed -- `context/ENGINEERING.md` - User-provided engineering seed - -**Actions**: -1. Read user-provided seeds -2. Research technologies, patterns, best practices -3. Grade evidence quality (High/Medium/Low confidence) -4. Expand seeds into full PRD using `workflows/templates/TEMPLATE-PRD.md` -5. Synthesize findings into structured document - -**Output**: -- `context/PRD.md` - Expanded PRD based on product seed -- `context/RESEARCH_SYNTHESIS.md` - Research synthesis - -**Success Criteria**: Research synthesis with sourced, graded claims - -### [APPROVAL GATE 1] - -User reviews: -- Expanded PRD in `context/PRD.md` -- Research synthesis document - -**Options**: -- ✅ **Approve** - Proceed to Phase 2 -- 🔄 **Request more research** - Specify areas needing deeper investigation -- ✏️ **Modify scope** - Adjust seeds and re-run - ---- - -## Phase 2: Architecture Planning - -**Role**: `architecture` -**Agent**: *[See Discovered Agents table]* - -**Input**: -- `context/PRD.md` - Expanded PRD from Phase 1 -- Research synthesis from Phase 1 -- `context/ENGINEERING.md` - Technical preferences -- Template skeleton (pyproject.toml, ADR.md, README.md, src/) - -**Actions**: -1. Create ADRs using `workflows/templates/TEMPLATE-ADR.md` -2. Define MVP scope using MoSCoW prioritization -3. Plan incremental feature roadmap using `workflows/templates/TEMPLATE-PROJECT-PLAN.md` -4. Customize template (pyproject.toml, README.md) - -**Output**: -- `ADR.md` - Overwritten with project-specific decisions -- `context/PROJECT_PLAN.md` - MVP scope + feature roadmap - -**Success Criteria**: Clear MVP definition, actionable roadmap - -### [APPROVAL GATE 2] - -User reviews: -- Architecture decisions in `ADR.md` -- MVP scope and feature roadmap in `context/PROJECT_PLAN.md` - -**Options**: -- ✅ **Approve** - Proceed to Phase 3 -- 🔧 **Adjust scope** - Modify MVP boundaries -- 📊 **Change priorities** - Reorder feature roadmap - ---- - -## Phase 3: MVP Implementation - -**Roles**: `implementation` + `review` -**Agents**: *[See Discovered Agents table - may use multiple specialists]* - -Phase 3 uses a structured **Implement → Review → Fix** loop for each deliverable to enforce test creation and code quality. - -Select implementation agent based on project type: - -| Project Type | Recommended Specialty | -|--------------|----------------------| -| RAG, embeddings, LLM integration | AI/ML specialist | -| APIs, databases, DDD | Backend specialist | -| Autonomous agents | Agentic specialist | -| ETL, data pipelines | Data specialist | - -**Input**: -- Approved `ADR.md` and `context/PROJECT_PLAN.md` from Phase 2 -- Customized template skeleton - ---- - -### 3.1 Implementation Sub-phase - -**Role**: `implementation` - -**Actions**: -1. Implement one deliverable (feature/module) from PROJECT_PLAN.md -2. Write unit tests following naming convention: `test____` -3. Ensure tests are behavioral (test outcomes, not mocks) -4. Run `just test` locally to verify tests pass -5. Mark deliverable as "Ready for Review" - -**Test Requirements**: -- Every new module must have corresponding unit tests -- Tests must follow naming convention from CLAUDE.md -- Minimum 80% coverage for new code -- No tautological tests (testing mocks, assignment, or nothing) - ---- - -### 3.2 Review Sub-phase - -**Role**: `review` (read-only) - -**Actions**: -1. Verify tests exist for all new implementation files -2. Check test naming conventions (`test____`) -3. Detect tautological tests (testing mocks instead of behavior) -4. Verify coverage >= 80% for new code -5. Check for hallucinated packages (imports that don't exist) -6. Scan for security vulnerabilities (bare except, SQL injection) -7. Generate review report - -**Blocking Criteria** (must fix before progression): -- [ ] Tests exist for all new implementation files -- [ ] Tests follow `test____` naming convention -- [ ] No tautological tests detected -- [ ] Coverage >= 80% for new code -- [ ] No hallucinated package imports -- [ ] No security vulnerabilities - -**Review Report Format**: -``` -## Test & Quality Review Report -**Deliverable**: [name] -**Status**: PASS | FAIL -**Coverage**: X% (required: 80%) -**Review Cycle**: N of 3 - -### Blocking Issues (must fix) -### Warnings (should fix) -### Passed Checks -### Remediation Required -``` - ---- - -### 3.3 Fix Sub-phase (If Review Fails) - -**Role**: `implementation` - -**Actions**: -1. Address each blocking issue from remediation list -2. Add missing tests if required -3. Fix tautological tests to be behavioral -4. Re-run `just test` locally -5. Return to 3.2 for re-review - -**Loop Control**: -- Maximum **3 fix cycles** per deliverable -- If still failing after 3 cycles → **escalate to user** - ---- - -### Validation Loop Diagram - -``` -PER DELIVERABLE: - -┌─────────────────┐ -│ IMPLEMENT │ ← implementation role (code + tests) -└────────┬────────┘ - │ - v -┌─────────────────┐ -│ REVIEW │ ← review role (read-only) -└────────┬────────┘ - │ - ┌────┴────┐ - │ PASS? │ - └────┬────┘ - Yes │ No - │ │ - ┌────┘ └────┐ - v v -┌──────┐ ┌──────┐ -│ DONE │ │ FIX │ ← implementation role -└──────┘ └──┬───┘ - │ - ┌────┴────┐ - │Cycle < 3│ - └────┬────┘ - Yes │ No - │ │ - (back to REVIEW) → ESCALATE TO USER -``` - ---- - -### Escalation Behavior - -If a deliverable fails review 3 times: - -1. **Generate Escalation Report** with: - - All persistent blocking issues - - Summary of attempted fixes across cycles - - Recommendations for resolution - -2. **Halt workflow** and present to user - -3. **User Options**: - - ⚠️ **Override** - Proceed anyway (document risk in PR) - - 🔧 **Manual fix** - User addresses issues directly - - ⏭️ **Descope** - Move feature to Phase 4 or backlog - - ✂️ **Split** - Break into smaller deliverables - ---- - -### Deliverable Tracking - -| Deliverable | Status | Cycle | Blocking Issues | Owner | -|-------------|--------|-------|-----------------|-------| -| *[Feature 1]* | Implementing | 0 | - | implementation | -| *[Feature 2]* | In Review | 1 | Missing tests for X | review | -| *[Feature 3]* | Passed | 2 | - | - | - ---- - -**Output**: Working MVP with tests (all deliverables passed review) - -**Success Criteria**: -- All deliverables pass review -- `just validate-branch` passes -- Coverage >= 80% for new code - -### [APPROVAL GATE 3] - -User validates: -- MVP functionality (end-to-end) -- All deliverables passed review loop -- Test coverage meets requirements - -**Options**: -- ✅ **Approve** - Proceed to Phase 4 -- 🐛 **Request fixes** - Specify additional issues to address -- ✏️ **Adjust scope** - Modify MVP boundaries - ---- - -## Phase 4: Iterative Enhancement - -**Roles**: `implementation` + `review` -**Agents**: *[Same specialists from Phase 3, or different per feature]* - -Phase 4 follows the same **Implement → Review → Fix** loop as Phase 3 for each feature in the roadmap. - -**Input**: -- Working MVP from Phase 3 -- Feature roadmap from `context/PROJECT_PLAN.md` - ---- - -### 4.1 Feature Implementation - -**Role**: `implementation` - -**Actions**: -1. Select next feature from PROJECT_PLAN.md roadmap (by priority) -2. Implement feature with unit tests -3. Follow same test requirements as Phase 3: - - Tests for all new modules - - `test____` naming - - 80% coverage for new code - - Behavioral tests (not tautological) -4. Run `just test` locally -5. Mark feature as "Ready for Review" - ---- - -### 4.2 Feature Review - -**Role**: `review` (read-only) - -**Actions**: -1. Run same validation as Phase 3.2 (tests, naming, coverage, quality) -2. Generate review report -3. If PASS → proceed to user approval -4. If FAIL → implementation agent fixes (max 3 cycles) - ---- - -### 4.3 Feature Approval - -### [APPROVAL GATE per feature] - -After review passes, user validates: -- Feature functionality -- Review report shows PASS -- Integration with existing MVP - -**Options**: -- ✅ **Approve** - Add next feature from roadmap -- 🔄 **Request changes** - Modify current feature -- ⏭️ **Skip to next** - Move to next roadmap item -- 🛑 **Stop** - End enhancement phase - ---- - -**Output**: Enhanced system with additional features - -**Success Criteria**: -- Each feature passes review loop -- `just validate-branch` passes -- Coverage maintained >= 80% - ---- - -## Folder Structure - -``` -project-root/ -├── context/ # User seeds + workflow outputs -│ ├── README.md # Instructions for seeds -│ ├── PRODUCT.md # User seed: product/business perspective -│ ├── ENGINEERING.md # User seed: technical perspective -│ ├── PRD.md # Phase 1 output: expanded PRD -│ └── PROJECT_PLAN.md # Phase 2 output: MVP scope + roadmap -├── workflows/ # Workflow support files -│ ├── PROJECT_INIT_WORKFLOW.md # This file -│ ├── QUICK-START.md # Step-by-step guide -│ ├── README.md # Template docs -│ └── templates/ # Output templates -│ ├── TEMPLATE-PRD.md -│ ├── TEMPLATE-ADR.md -│ └── TEMPLATE-PROJECT-PLAN.md -├── ADR.md # Overwritten in Phase 2 -└── src/ # Implementation (Phase 3-4) -``` - ---- - -## Artifact Locations - -| Artifact | Location | Created By | -|----------|----------|------------| -| User seeds | `context/PRODUCT.md`, `context/ENGINEERING.md` | **User** (before workflow) | -| Output templates | `workflows/templates/` | System (part of template) | -| Expanded PRD | `context/PRD.md` | `research` role (Phase 1) | -| Research synthesis | `context/RESEARCH_SYNTHESIS.md` | `research` role (Phase 1) | -| Architecture decisions | `ADR.md` | `architecture` role (Phase 2) | -| Project plan | `context/PROJECT_PLAN.md` | `architecture` role (Phase 2) | -| Implementation | `src/*.py` | `implementation` role (Phase 3-4) | - ---- - -## Invocation Examples - -**Step 0** - Fill out seeds: -``` -Edit context/PRODUCT.md and context/ENGINEERING.md with your project details -``` - -**Phase 0** - Discover agents: -``` -Run the project initialization workflow -``` -Claude Code will scan for specialists, present them, and update this file. - -**Phase 1** - Start context research: -``` -Research context for this project using [discovered research agent] -``` - -**Phase 2** - Plan architecture: -``` -Plan architecture for this project using [discovered architecture agent] -``` - -**Phase 3** - Implement MVP: -``` -Implement MVP using [discovered implementation agent(s)] -``` - -**Phase 4** - Add features: -``` -Add [feature name] from the roadmap using [appropriate implementation agent] -``` - ---- - -## Template Usage - -Templates in `workflows/templates/` define output formats. Agents use these to produce consistent documents. - -### PRD Template → `context/PRD.md` - -**Used by**: `research` role (Phase 1) - -**Key sections**: -- Problem Statement (from user seeds) -- Objectives (from success criteria) -- User Stories with acceptance criteria -- Constraints (from engineering seed) - -### ADR Template → `ADR.md` - -**Used by**: `architecture` role (Phase 2) - -**Typical decisions**: -- ADR-001: Database choice -- ADR-002: Web framework -- ADR-003: Authentication -- ADR-004: Deployment -- ADR-005: State management - -**Each ADR must have**: Context, Decision, Consequences, Alternatives - -### Project Plan Template → `context/PROJECT_PLAN.md` - -**Used by**: `architecture` role (Phase 2) - -**Key sections**: -- Overview table with project details -- Phase status tracking -- MVP Scope (Must-Have features only) -- Feature Roadmap (Should/Could/Won't) - ---- - -## Troubleshooting - -### "Agent doesn't understand requirements" - -**Cause**: User description too vague or context missing - -**Fix**: -- Provide more specific problem statement -- Describe target users explicitly -- Include examples of desired functionality -- State constraints clearly - -### "ADR doesn't match expectations" - -**Cause**: PRD unclear or research missed key requirements - -**Fix**: -- Review PRD - is problem statement clear? -- Provide direct feedback on what to change -- Edit ADR directly if easier - -### "MVP scope too large/small" - -**Cause**: Unclear boundaries in PRD or misaligned priorities - -**Fix**: -- Review Must-Have vs. Should-Have in PRD -- Explicitly state what's NOT in MVP -- Adjust PROJECT_PLAN.md scope directly - -### "Feature implementation diverges from plan" - -**Cause**: Agent didn't read context or context unclear - -**Fix**: -- Ensure ADR has "Accepted" status -- Ask agent to re-read specific context file -- Update context if requirements changed - ---- - -## Agent Best Practices - -1. **Read all context before acting**: Don't skip to implementation -2. **Ask clarifying questions**: Don't guess user intent -3. **One phase at a time**: Don't jump ahead -4. **Follow templates exactly**: Consistency matters -5. **Cross-reference liberally**: Link to sources and related docs - ---- - -## Workflow Refinement - -After each workflow execution, update this file to: - -- [ ] Refine phase instructions based on learnings -- [ ] Add project-type-specific guidance -- [ ] Improve success criteria -- [ ] Document common issues and solutions - -### Refinement Log - -| Date | Change | Reason | -|------|--------|--------| -| *Initial* | Created workflow | Template adaptation needs | -| 2025-11-28 | Reorganized: context/ for seeds, workflows/ for support | Clearer separation of user inputs vs. system files | -| 2025-11-28 | Added Phase 0 agent discovery, abstract roles | Workflow portability - users may have different specialists | -| 2025-11-28 | Added `review` role with Implement → Review → Fix loop | Enforce test creation and code quality before progression | diff --git a/workflows/templates/TEMPLATE-ADR.md b/workflows/templates/TEMPLATE-ADR.md deleted file mode 100644 index 92af24b..0000000 --- a/workflows/templates/TEMPLATE-ADR.md +++ /dev/null @@ -1,361 +0,0 @@ -# Architecture Decision Records - ---- -**Status**: Active -**Created**: [YYYY-MM-DD] -**Last Updated**: [YYYY-MM-DD] ---- - -This document captures significant architectural decisions made during the project. Each decision is recorded with context, rationale, and consequences. - -**Format**: Each ADR follows the structure: -- **Title**: Short noun phrase -- **Status**: Proposed | Accepted | Deprecated | Superseded -- **Date**: When decision was made -- **Context**: Problem or requirement -- **Decision**: What was chosen -- **Consequences**: Positive, negative, and risks -- **Alternatives**: Other options considered - ---- - -## ADR-001: [Decision Title] - -**Status**: Accepted -**Date**: [YYYY-MM-DD] -**Deciders**: [Roles/names] - -### Context - -[2-3 paragraphs describing]: -- What problem or requirement drove this decision? -- What constraints affected the choice? -- What was the existing situation (if applicable)? - -Example: -> The application needs to persist user data, research findings, and project metadata. Requirements include ACID transactions for user operations, JSON field support for flexible research metadata storage, and full-text search for knowledge retrieval. The team has strong PostgreSQL experience but limited NoSQL expertise. Budget allows for managed database services. - -### Decision - -[Clear statement of what was chosen] - -Example: -> We will use **PostgreSQL 15+** as the primary database for all application data. - -**Key implementation details**: -- [Specific approach point 1] -- [Specific approach point 2] -- [Specific approach point 3] - -Example: -- Use `jsonb` columns for research metadata (flexible schema) -- Implement full-text search with GIN indexes on document content -- Deploy via managed service (AWS RDS or GCP Cloud SQL) -- Use connection pooling (pgbouncer) for efficiency - -### Consequences - -#### Positive -- [Benefit 1] -- [Benefit 2] -- [Benefit 3] - -Example: -- Native JSON support eliminates need for separate document store -- ACID guarantees ensure data consistency for critical operations -- Strong ecosystem (ORMs, migration tools, monitoring) -- Team expertise reduces ramp-up time - -#### Negative -- [Trade-off 1] -- [Trade-off 2] - -Example: -- More complex operations than managed NoSQL (manual backups, tuning) -- Vertical scaling limits (plan for read replicas if traffic grows) -- Higher baseline cost than serverless databases - -#### Risks -- [Risk 1 and mitigation] -- [Risk 2 and mitigation] - -Example: -- **Risk**: Database becomes bottleneck at scale - - **Mitigation**: Implement read replicas and caching (Redis) early -- **Risk**: Team unfamiliar with PostgreSQL-specific optimizations - - **Mitigation**: Allocate 2 weeks for training and performance testing - -### Alternatives Considered - -#### Alternative 1: [Name] -- **Pros**: [Benefits] -- **Cons**: [Drawbacks] -- **Why rejected**: [Reason] - -Example: -#### Alternative 1: MongoDB (Document Store) -- **Pros**: Flexible schema, horizontal scaling, native JSON -- **Cons**: No ACID transactions (until v4.2), team unfamiliarity, complex aggregation queries -- **Why rejected**: ACID requirements and team expertise outweigh schema flexibility benefits - -#### Alternative 2: [Name] -- **Pros**: [Benefits] -- **Cons**: [Drawbacks] -- **Why rejected**: [Reason] - ---- - -## ADR-002: [Decision Title] - -**Status**: Accepted -**Date**: [YYYY-MM-DD] -**Deciders**: [Roles/names] - -### Context - -[Problem description] - -Example: -> The application requires a web API for client interactions and background task processing for long-running research jobs. Performance requirements include <100ms response time for 95% of API requests and support for concurrent processing of multiple research tasks. - -### Decision - -Example: -> We will use **FastAPI** (Python 3.11+) with **async/await** for the web framework. - -**Key implementation details**: -- Async endpoints for I/O-bound operations (database, external APIs) -- Background tasks via Celery with Redis message broker -- Pydantic models for request/response validation -- OpenAPI auto-generation for API documentation - -### Consequences - -#### Positive -- Native async support (better concurrency than Flask/Django) -- Automatic request validation and serialization (Pydantic) -- Modern Python features (type hints, async) -- Fast development with auto-generated docs - -#### Negative -- Smaller ecosystem than Flask/Django (fewer plugins) -- Team needs to learn async patterns -- Debugging async code more complex - -#### Risks -- **Risk**: Async code introduces race conditions - - **Mitigation**: Use async-safe libraries, comprehensive testing -- **Risk**: CPU-bound tasks block event loop - - **Mitigation**: Offload to Celery workers, not async endpoints - -### Alternatives Considered - -#### Alternative 1: Django REST Framework -- **Pros**: Batteries-included, large ecosystem, team familiarity -- **Cons**: Not async-native (ASGI support limited), heavier than needed -- **Why rejected**: Performance requirements favor async-first framework - -#### Alternative 2: Flask with async extensions -- **Pros**: Lightweight, team familiarity, large ecosystem -- **Cons**: Async support bolted-on (not native), manual validation -- **Why rejected**: FastAPI provides better DX for async and validation - ---- - -## ADR-003: [Decision Title - Authentication] - -**Status**: Accepted -**Date**: [YYYY-MM-DD] -**Deciders**: [Roles/names] - -### Context - -[Problem description] - -Example: -> Application requires user authentication for personalized research storage and multi-user collaboration. Must support both web UI and API access. Security requirements include password hashing, session management, and rate limiting. - -### Decision - -Example: -> We will use **OAuth 2.0 with JWT tokens** for authentication and **role-based access control (RBAC)** for authorization. - -**Key implementation details**: -- JWT tokens with 1-hour expiration, refresh tokens with 7-day expiration -- Password hashing via bcrypt (cost factor 12) -- Social login (Google, GitHub) via OAuth providers -- Roles: Admin, Researcher, Viewer - -### Consequences - -[Fill in positive, negative, risks as above] - -### Alternatives Considered - -[Fill in alternatives as above] - ---- - -## ADR-004: [Decision Title - Deployment] - -**Status**: Proposed -**Date**: [YYYY-MM-DD] -**Deciders**: [Roles/names] - -### Context - -Example: -> Application needs to be deployed with high availability, automatic scaling, and minimal operational overhead. Budget allows for managed services. Team prefers infrastructure-as-code for reproducibility. - -### Decision - -Example: -> We will deploy on **Google Cloud Platform (GCP)** using: -- Cloud Run for application containers (auto-scaling) -- Cloud SQL for PostgreSQL (managed database) -- Cloud Storage for file uploads -- Terraform for infrastructure provisioning - -**Key implementation details**: -- Docker multi-stage builds for optimized images -- CI/CD via GitHub Actions -- Staging and production environments -- Cost alerts at $500/month threshold - -### Consequences - -[Fill in as above] - -### Alternatives Considered - -#### Alternative 1: AWS (ECS + RDS + S3) -- **Pros**: Broader service catalog, more community resources -- **Cons**: More complex pricing, steeper learning curve -- **Why rejected**: Team familiarity with GCP, simpler pricing model - -#### Alternative 2: Heroku -- **Pros**: Simplest deployment, zero-config -- **Cons**: Higher cost at scale, less control -- **Why rejected**: Cost becomes prohibitive beyond hobby tier - ---- - -## ADR-005: [Decision Title - State Management] - -**Status**: Accepted -**Date**: [YYYY-MM-DD] -**Deciders**: [Roles/names] - -### Context - -[Problem description for state management, caching, session storage] - -### Decision - -[Your choice - Redis, in-memory, database sessions, etc.] - -### Consequences - -[Fill in as above] - -### Alternatives Considered - -[Fill in as above] - ---- - -## Template for New ADRs - -Copy this template when adding a new decision: - -```markdown -## ADR-XXX: [Short Descriptive Title] - -**Status**: Proposed | Accepted | Deprecated | Superseded -**Date**: YYYY-MM-DD -**Deciders**: [Roles/names] - -### Context -[What problem requires a decision? What constraints exist?] - -### Decision -[What is being decided?] - -**Key implementation details**: -- [Detail 1] -- [Detail 2] - -### Consequences - -#### Positive -- [Benefit] - -#### Negative -- [Trade-off] - -#### Risks -- **Risk**: [Description] - - **Mitigation**: [How we'll address it] - -### Alternatives Considered - -#### Alternative 1: [Name] -- **Pros**: [Benefits] -- **Cons**: [Drawbacks] -- **Why rejected**: [Reason] -``` - ---- - -## ADR Status Definitions - -| Status | Meaning | Agent Behavior | -|--------|---------|----------------| -| **Proposed** | Under consideration, not yet approved | Consider but don't enforce | -| **Accepted** | Approved and active | **Mandatory** - must follow this decision | -| **Deprecated** | No longer recommended but not forbidden | Avoid in new code, flag in reviews | -| **Superseded** | Replaced by newer decision | **Actively avoid** - use new decision instead | - ---- - -## Decision Index - -Quick reference for all decisions: - -| ADR | Title | Status | Date | -|-----|-------|--------|------| -| 001 | [Database Choice] | Accepted | [YYYY-MM-DD] | -| 002 | [Web Framework] | Accepted | [YYYY-MM-DD] | -| 003 | [Authentication] | Accepted | [YYYY-MM-DD] | -| 004 | [Deployment Platform] | Proposed | [YYYY-MM-DD] | -| 005 | [State Management] | Accepted | [YYYY-MM-DD] | - ---- - -## Notes for AI Agents - -**When reading this document**: -- Apply **Accepted** decisions as mandatory constraints -- Avoid **Deprecated** and **Superseded** approaches -- Consider **Proposed** decisions but confirm with user before implementing -- Check alternatives if requirements don't fit accepted decision - -**When adding a new ADR**: -- Assign next sequential number (ADR-XXX) -- Set status to "Proposed" initially -- Include at least 2 alternatives considered -- Update Decision Index table at bottom -- Add date to document's "Last Updated" field - -**Common ADR Topics**: -- Database technology -- Web framework -- Authentication/authorization -- API design (REST vs. GraphQL) -- Frontend framework (if applicable) -- Deployment platform -- CI/CD approach -- Monitoring/logging strategy -- Testing strategy -- State management -- Error handling approach diff --git a/workflows/templates/TEMPLATE-PRD.md b/workflows/templates/TEMPLATE-PRD.md deleted file mode 100644 index 74e0b69..0000000 --- a/workflows/templates/TEMPLATE-PRD.md +++ /dev/null @@ -1,303 +0,0 @@ -# Product Requirements Document: [Project Name] - ---- -**Status**: Draft -**Created**: [YYYY-MM-DD] -**Last Updated**: [YYYY-MM-DD] -**Owner**: [Role/Name] -**Version**: 0.1 ---- - -## Problem Statement - -**2-3 sentences describing**: -- Who is affected: [target users/stakeholders] -- What problem exists: [core pain point] -- Impact if not solved: [business/user consequence] - -Example: -> Software developers spend 40% of their time context-switching between tools when researching technical decisions. This fragmentation leads to inconsistent documentation and repeated research across team members. Without a centralized knowledge system, teams lose productivity and struggle to onboard new members effectively. - ---- - -## Objectives & Key Results (OKRs) - -### Business Objective -[What is the desired outcome?] - -Example: Enable teams to make faster, better-informed technical decisions. - -### Key Results - -1. **[Measurable indicator 1]**: [Target metric] - - Baseline: [Current state] - - Goal: [Target state] - -2. **[Measurable indicator 2]**: [Target metric] - - Baseline: [Current state] - - Goal: [Target state] - -3. **[Measurable indicator 3]**: [Target metric] - - Baseline: [Current state] - - Goal: [Target state] - -Example: -1. **Research time reduction**: 40% → 20% of developer time - - Baseline: 16 hours/week per developer - - Goal: 8 hours/week per developer - -2. **Documentation consistency**: 30% → 80% of decisions documented - - Baseline: 3 of 10 decisions have written rationale - - Goal: 8 of 10 decisions have written rationale - ---- - -## User Stories - -Use format: "As a [user type], I want [capability] so that [benefit]" - -### Core User Stories (Must-Have) - -#### US-001: [Story Title] -**As a** [user role] -**I want** [specific capability] -**So that** [business value/benefit] - -**Acceptance Criteria**: -- [ ] [Testable condition 1] -- [ ] [Testable condition 2] -- [ ] [Testable condition 3] - -**Dependencies**: [Other stories, external systems, or "None"] - -**Priority**: Must-Have - ---- - -#### US-002: [Story Title] -**As a** [user role] -**I want** [specific capability] -**So that** [business value/benefit] - -**Acceptance Criteria**: -- [ ] [Testable condition 1] -- [ ] [Testable condition 2] - -**Dependencies**: [Other stories or "None"] - -**Priority**: Must-Have - ---- - -### Additional User Stories (Should-Have / Could-Have) - -#### US-003: [Story Title] -**Priority**: Should-Have - -[Same format as above] - ---- - -## Solution Requirements - -### High-Level Approach - -[1-2 paragraphs describing the proposed solution architecture] - -Example: -> The system will consist of a web-based interface for research input and a command-line tool for developer workflows. A vector database will store research findings with metadata for efficient retrieval. AI agents will synthesize findings and suggest architectural decisions based on project context. - -### Functional Requirements - -#### Must-Have (MVP) - -1. **[Feature 1]**: [Description] - - [Sub-requirement 1.1] - - [Sub-requirement 1.2] - -2. **[Feature 2]**: [Description] - - [Sub-requirement 2.1] - - [Sub-requirement 2.2] - -3. **[Feature 3]**: [Description] - -Example: -1. **Research Collection**: System must capture web research findings - - Extract content from URLs (docs, blogs, GitHub) - - Grade evidence quality (High/Medium/Low) - - Store with source attribution and timestamps - -2. **Knowledge Synthesis**: System must consolidate findings across sources - - Deduplicate information - - Resolve contradictions - - Identify gaps in coverage - -#### Should-Have (Post-MVP Priority) - -1. **[Feature]**: [Description] -2. **[Feature]**: [Description] - -#### Could-Have (Nice to Have) - -1. **[Feature]**: [Description] -2. **[Feature]**: [Description] - -#### Won't-Have (Out of Scope for V1) - -1. **[Feature]**: [Reason for exclusion] -2. **[Feature]**: [Reason for exclusion] - -### Non-Functional Requirements - -#### Performance -- **[Metric]**: [Target] - - Example: **Response time**: < 2 seconds for 95th percentile queries - -#### Scalability -- **[Metric]**: [Target] - - Example: **Concurrent users**: Support 100 simultaneous users - -#### Security -- **[Requirement]**: [Description] - - Example: **Authentication**: OAuth 2.0 with role-based access control - -#### Reliability -- **[Metric]**: [Target] - - Example: **Uptime**: 99.5% availability (excluding planned maintenance) - -#### Usability -- **[Requirement]**: [Description] - - Example: **Learning curve**: New users productive within 30 minutes - ---- - -## Acceptance Criteria (Overall) - -**The project is successful when**: - -- [ ] [Measurable criterion 1] -- [ ] [Measurable criterion 2] -- [ ] [Measurable criterion 3] -- [ ] [Measurable criterion 4] - -Example: -- [ ] 80% of user stories marked "Must-Have" are implemented and tested -- [ ] End-to-end workflow (research → synthesis → decision) completes without errors -- [ ] Documentation coverage > 90% (all public APIs documented) -- [ ] `just validate-branch` passes (all tests, type checks, linting) - ---- - -## Constraints & Assumptions - -### Technical Constraints - -1. **[Constraint]**: [Description and impact] - - Example: **Python 3.11+ only**: Leverages modern type hints and performance improvements - -2. **[Constraint]**: [Description and impact] - - Example: **OpenAI API required**: No offline mode in V1 - -### Business Constraints - -1. **[Constraint]**: [Description and impact] - - Example: **Budget**: $500/month max for API costs - -2. **[Constraint]**: [Description and impact] - - Example: **Timeline**: MVP must launch within 8 weeks - -### Assumptions - -1. **[Assumption]**: [What we're assuming is true] - - Example: **User expertise**: Users have basic command-line proficiency - -2. **[Assumption]**: [What we're assuming is true] - - Example: **Data availability**: Research sources (docs, blogs) remain accessible - ---- - -## Success Metrics - -**How we'll measure success post-launch**: - -| Metric | Target | Measurement Method | -|--------|--------|-------------------| -| [Metric name] | [Target value] | [How measured] | -| User adoption | 20 active users within 1 month | Analytics dashboard | -| Research quality | 90% of syntheses rated "helpful" | User survey | -| Time savings | 50% reduction in research time | Before/after comparison | - ---- - -## User Personas (Optional) - -### Persona 1: [Name/Role] - -**Background**: [Brief description] - -**Goals**: -- [Goal 1] -- [Goal 2] - -**Pain Points**: -- [Pain point 1] -- [Pain point 2] - -**How This Project Helps**: [1-2 sentences] - ---- - -### Persona 2: [Name/Role] - -[Same structure as above] - ---- - -## Open Questions - -**Unresolved issues that need clarification**: - -1. **[Question]**: [Description] - - **Blocker?**: Yes/No - - **Owner**: [Who will resolve] - - **Target date**: [YYYY-MM-DD] - -2. **[Question]**: [Description] - - **Blocker?**: Yes/No - - **Owner**: [Who will resolve] - ---- - -## Appendix - -### Related Documents -- [Architecture Decisions](../ADR.md) -- [Project Plan](./PROJECT_PLAN.md) -- [Research Synthesis](./RESEARCH_SYNTHESIS.md) - -### Glossary -- **[Term]**: [Definition] -- **[Term]**: [Definition] - -### Change Log - -| Date | Change | Author | -|------|--------|--------| -| [YYYY-MM-DD] | Initial draft created | [Name] | -| [YYYY-MM-DD] | Added US-005 based on user feedback | [Name] | - ---- - -## Notes for AI Agents - -**When reading this PRD**: -- Focus on "Must-Have" requirements for MVP scope -- Prioritize user stories with no dependencies first -- Flag ambiguous acceptance criteria before implementation -- Cross-reference with ADR.md for architectural constraints - -**When updating this PRD**: -- Add date and reason to Change Log -- Update version number (increment by 0.1 for minor, 1.0 for major) -- Notify team if changing "Must-Have" scope -- Preserve existing user story IDs (don't renumber) diff --git a/workflows/templates/TEMPLATE-PROJECT-PLAN.md b/workflows/templates/TEMPLATE-PROJECT-PLAN.md deleted file mode 100644 index b0f66e9..0000000 --- a/workflows/templates/TEMPLATE-PROJECT-PLAN.md +++ /dev/null @@ -1,418 +0,0 @@ -# Project Plan: [Project Name] - ---- -**Status**: Active -**Created**: [YYYY-MM-DD] -**Last Updated**: [YYYY-MM-DD] -**Current Phase**: Phase 1 - Context Research ---- - -## Overview - -| Aspect | Details | -|--------|---------| -| **Project Goal** | [1 sentence describing end state] | -| **Target Users** | [Primary user personas] | -| **Success Criteria** | [How we measure success] | -| **Timeline** | [Estimated duration or target date] | -| **Team Size** | [Number of contributors] | - -Example: -| Aspect | Details | -|--------|---------| -| **Project Goal** | Enable developers to capture, synthesize, and retrieve research findings efficiently | -| **Target Users** | Software engineers, technical leads, architects | -| **Success Criteria** | 50% reduction in research time, 80% of decisions documented | -| **Timeline** | 8 weeks to MVP, 4 weeks for enhancement phase | -| **Team Size** | 2 developers + 1 PM | - ---- - -## Phase 1: Context Research - -**Status**: [Not Started | In Progress | Complete | Blocked] -**Owner**: context-engineer -**Duration**: [Estimated time] - -### Objectives - -1. [Objective 1] -2. [Objective 2] -3. [Objective 3] - -Example: -1. Understand technical landscape for chosen domain -2. Identify best practices and anti-patterns -3. Create structured context for architecture planning - -### Deliverables - -- [ ] `context/` folder structure created -- [ ] `context/product/PRD.md` drafted (based on user input) -- [ ] `context/research/technology-comparison.md` completed -- [ ] `context/research/best-practices.md` completed -- [ ] `~/.claude/context/research/{project}-synthesis.md` written - -### Success Criteria - -- [ ] Research synthesis includes 5+ sources with evidence grades -- [ ] PRD has complete "Must-Have" user stories -- [ ] All claims in research docs are sourced -- [ ] User approves context structure and content - -### Blockers & Risks - -| Issue | Impact | Mitigation | Owner | -|-------|--------|------------|-------| -| [Blocker/risk] | High/Med/Low | [How to address] | [Who] | - -Example: -| Issue | Impact | Mitigation | Owner | -|-------|--------|------------|-------| -| Insufficient user requirements | High | Schedule clarification meeting | PM | -| Technology rapidly evolving | Medium | Focus on stable core, flag experimental | context-engineer | - ---- - -## Phase 2: Architecture Planning - -**Status**: [Not Started | In Progress | Complete | Blocked] -**Owner**: project-architect -**Duration**: [Estimated time] - -### Objectives - -1. [Objective 1] -2. [Objective 2] - -Example: -1. Make and document key architectural decisions -2. Define clear MVP scope with feature roadmap -3. Prepare template skeleton for implementation - -### Deliverables - -- [ ] `context/architecture/ADR.md` with 3-5 decisions -- [ ] `context/planning/PROJECT_PLAN.md` (this file) completed -- [ ] `pyproject.toml` updated with dependencies -- [ ] `README.md` customized for project -- [ ] `src/` folder structure created (if applicable) - -### Success Criteria - -- [ ] Each ADR follows standard format (Context/Decision/Consequences) -- [ ] MVP scope clearly separates Must/Should/Could/Won't -- [ ] Roadmap has at least 5 prioritized features -- [ ] User approves architecture and plan - -### Dependencies - -- **Requires**: Phase 1 complete (approved PRD and research) -- **Blocks**: Phase 3 (cannot start implementation without plan) - -### Blockers & Risks - -[Same table format as Phase 1] - ---- - -## Phase 3: MVP Implementation - -**Status**: [Not Started | In Progress | Complete | Blocked] -**Owner**: [domain-specialist - select based on project type] -**Duration**: [Estimated time] - -### Objectives - -1. Implement all "Must-Have" features -2. Create end-to-end working system -3. Establish testing and validation pipeline - -### MVP Scope - -#### Must-Have Features (In Scope) - -| Feature | Description | Acceptance Criteria | Status | -|---------|-------------|---------------------|--------| -| [Feature 1] | [Brief description] | [How to test] | Not Started | -| [Feature 2] | [Brief description] | [How to test] | Not Started | -| [Feature 3] | [Brief description] | [How to test] | Not Started | - -Example: -| Feature | Description | Acceptance Criteria | Status | -|---------|-------------|---------------------|--------| -| User Auth | Email/password login | User can register, login, logout | Not Started | -| Research Capture | Save web findings with metadata | User can add URL, extract content, save to DB | Not Started | -| Search | Full-text search of findings | User can search and get ranked results | Not Started | - -#### Out of Scope (MVP) - -**These features are intentionally excluded from MVP**: -- [Feature] - [Reason for exclusion] -- [Feature] - [Reason for exclusion] - -Example: -- Social login (Google/GitHub) - Adds complexity without validating core value -- Real-time collaboration - Not needed for single-user validation -- Mobile app - Web-first approach, mobile later if needed - -### Deliverables - -- [ ] All Must-Have features implemented -- [ ] Unit tests for core functionality (>70% coverage) -- [ ] Integration tests for end-to-end flows -- [ ] Documentation updated (README, API docs) -- [ ] `just validate-branch` passes - -### Success Criteria - -- [ ] End-to-end user workflow completes without errors -- [ ] All acceptance criteria met for Must-Have features -- [ ] Test suite passes (`just test`) -- [ ] Type checking passes (`just type-check`) -- [ ] Linting passes (`just lint`) -- [ ] User validates MVP functionality - -### Dependencies - -- **Requires**: Phase 2 complete (approved architecture and plan) -- **Blocks**: Phase 4 (cannot enhance without working MVP) - -### Blockers & Risks - -[Same table format as Phase 1] - ---- - -## Phase 4: Iterative Enhancement - -**Status**: [Not Started | In Progress | Complete | Blocked] -**Owner**: [same domain-specialist from Phase 3] -**Duration**: [Estimated time or "Ongoing"] - -### Objectives - -1. Incrementally add features from roadmap -2. Incorporate user feedback -3. Maintain quality as system grows - -### Feature Roadmap - -Features prioritized using **MoSCoW**: -- **Must**: Critical for initial release -- **Should**: Important but not critical -- **Could**: Nice to have if time permits -- **Won't**: Out of scope for V1 - -| Priority | Feature | Description | Dependencies | Status | -|----------|---------|-------------|--------------|--------| -| Must | [Feature] | [Brief desc] | [Other features] | Not Started | -| Should | [Feature] | [Brief desc] | [Other features] | Not Started | -| Should | [Feature] | [Brief desc] | [Other features] | Not Started | -| Could | [Feature] | [Brief desc] | [Other features] | Not Started | -| Won't | [Feature] | [Brief desc] | - | Deferred | - -Example: -| Priority | Feature | Description | Dependencies | Status | -|----------|---------|-------------|--------------|--------| -| Must | Social Login | Google/GitHub OAuth | User Auth | Not Started | -| Must | Export Results | Download research as Markdown/PDF | Search | Not Started | -| Should | Tagging System | Categorize findings by topic | Research Capture | Not Started | -| Should | Sharing | Share findings with team | User Auth | Not Started | -| Could | Browser Extension | Capture research from browser | API | Not Started | -| Won't | AI Summarization | Auto-summarize long articles | - | Deferred to V2 | - -### Implementation Approach - -**Per Feature**: -1. Review feature requirements and acceptance criteria -2. Update architecture if needed (new ADR) -3. Implement feature in isolated branch -4. Add tests (unit + integration) -5. Update documentation -6. Submit for user approval -7. Merge after approval - -**Approval Gates**: User reviews each feature before next begins - -### Success Criteria (Per Feature) - -- [ ] Feature meets acceptance criteria from roadmap -- [ ] Tests added and passing -- [ ] Documentation updated -- [ ] No regression in existing functionality -- [ ] `just validate-branch` passes - -### Dependencies - -- **Requires**: Phase 3 complete (working MVP) -- **Enables**: Production release - -### Blockers & Risks - -[Same table format as Phase 1] - ---- - -## Milestones - -**High-level project checkpoints**: - -| Milestone | Target Date | Criteria | Status | -|-----------|-------------|----------|--------| -| Phase 1 Complete | [YYYY-MM-DD] | Context approved | Not Started | -| Phase 2 Complete | [YYYY-MM-DD] | Architecture approved | Not Started | -| MVP Launch | [YYYY-MM-DD] | All Must-Haves working | Not Started | -| V1.0 Release | [YYYY-MM-DD] | All Should-Haves complete | Not Started | - ---- - -## Technical Milestones - -**Infrastructure and tooling setup**: - -| Milestone | Description | Owner | Status | -|-----------|-------------|-------|--------| -| Dev Environment | Docker compose, local DB | [Name] | Not Started | -| CI/CD Pipeline | GitHub Actions, auto-deploy staging | [Name] | Not Started | -| Monitoring | Logging, error tracking, metrics | [Name] | Not Started | -| Production Deploy | Cloud deployment, custom domain | [Name] | Not Started | - ---- - -## Metrics & KPIs - -**How we measure progress and success**: - -### Development Metrics - -| Metric | Target | Current | Tracking Method | -|--------|--------|---------|-----------------| -| Test Coverage | >70% | 0% | pytest-cov | -| Type Coverage | >90% | 0% | mypy strict mode | -| Build Success Rate | >95% | N/A | GitHub Actions | - -### Product Metrics (Post-Launch) - -| Metric | Target | Current | Tracking Method | -|--------|--------|---------|-----------------| -| Active Users | 20/month | 0 | Analytics dashboard | -| Research Quality | 90% "helpful" | N/A | User survey | -| Time Savings | 50% reduction | N/A | Before/after comparison | - ---- - -## Dependencies & Integrations - -**External systems and services**: - -| Dependency | Purpose | Status | Risk | -|------------|---------|--------|------| -| [Service] | [What it's for] | [Integrated/Pending] | High/Med/Low | - -Example: -| Dependency | Purpose | Status | Risk | -|------------|---------|--------|------| -| OpenAI API | LLM for synthesis | Integrated | Low - stable API | -| PostgreSQL | Primary database | Integrated | Low - mature tech | -| OAuth Providers | Social login | Pending | Medium - config complexity | -| AWS S3 | File storage | Not started | Low - well-documented | - ---- - -## Risk Register - -**Ongoing risks and mitigations**: - -| Risk | Probability | Impact | Mitigation | Owner | -|------|-------------|--------|------------|-------| -| [Risk description] | High/Med/Low | High/Med/Low | [How to address] | [Who] | - -Example: -| Risk | Probability | Impact | Mitigation | Owner | -|------|-------------|--------|------------|-------| -| Scope creep in MVP | Medium | High | Strict adherence to Must-Have list, defer to Phase 4 | PM | -| API cost exceeds budget | Low | Medium | Implement caching, rate limiting, cost alerts | Backend Dev | -| Key developer unavailable | Low | High | Documentation, knowledge sharing, pair programming | Team Lead | - ---- - -## Change Log - -**Track significant plan updates**: - -| Date | Change | Reason | Author | -|------|--------|--------|--------| -| [YYYY-MM-DD] | Initial plan created | Project kickoff | [Name] | -| [YYYY-MM-DD] | Added Social Login to Should-Have | User feedback | [Name] | -| [YYYY-MM-DD] | Moved AI Summarization to Won't | Complexity vs. value | [Name] | - ---- - -## Notes for AI Agents - -### Phase Transitions - -**Before starting each phase**: -1. Read all deliverables from previous phase -2. Validate dependencies are met -3. Confirm success criteria are clear and measurable -4. Check for blockers and flag to user - -**After completing each phase**: -1. Mark all deliverables as complete -2. Update phase status to "Complete" -3. Prepare handoff summary for next phase -4. Request user approval before proceeding - -### Roadmap Execution (Phase 4) - -**When implementing features from roadmap**: -1. Work on highest priority (Must → Should → Could) -2. Check dependencies (implement prerequisites first) -3. Implement one feature at a time (don't parallelize) -4. Request approval after each feature before next - -**If feature blocked**: -1. Mark status as "Blocked" -2. Document blocker in Blockers & Risks table -3. Move to next unblocked feature -4. Flag to user - -### Updating This Plan - -**When to update**: -- Feature status changes (Not Started → In Progress → Complete) -- New risks identified -- Priorities change -- Blockers encountered -- Milestones reached - -**How to update**: -1. Update relevant table/section -2. Add entry to Change Log -3. Update "Last Updated" date at top -4. Notify user if significant change (scope, timeline) - ---- - -## Quick Reference - -### Current Sprint Focus -**[Brief description of current work]** - -Example: -> Implementing Phase 3 MVP - Focus on Research Capture feature (US-002). Target: Complete by [date]. - -### Next 3 Priorities -1. [Priority 1] -2. [Priority 2] -3. [Priority 3] - -### Blockers Needing Attention -- [Blocker 1] - Owner: [Name] -- [Blocker 2] - Owner: [Name] - -### Upcoming Approvals -- [ ] [Approval 1] - Due: [date] -- [ ] [Approval 2] - Due: [date]