diff --git a/.agent/workflows/backend-logs.md b/.agent/workflows/backend.logs.md similarity index 100% rename from .agent/workflows/backend-logs.md rename to .agent/workflows/backend.logs.md diff --git a/.agent/workflows/bugfix-description.md b/.agent/workflows/bugfix.description.md similarity index 100% rename from .agent/workflows/bugfix-description.md rename to .agent/workflows/bugfix.description.md diff --git a/.agent/workflows/bugfix-report.md b/.agent/workflows/bugfix.report.md similarity index 100% rename from .agent/workflows/bugfix-report.md rename to .agent/workflows/bugfix.report.md diff --git a/.agent/workflows/codemap.md b/.agent/workflows/codemap.md new file mode 100644 index 0000000000..7ee57b9208 --- /dev/null +++ b/.agent/workflows/codemap.md @@ -0,0 +1,66 @@ +--- +description: Generate a comprehensive technical "codemap" document for a specific feature in the codebase. +--- + +# /codemap + +Generate a comprehensive technical "codemap" document for a specific feature in the codebase. + +## Purpose +To create a detailed, deep-dive technical reference document (`[feature]-codemap.md`) that maps out the file structure, architecture, data flow, and core components of a specific feature. This helps developers quickly understand complex parts of the system. + +## Instructions + +### 1. Analyze the Request +- **If the user DOES NOT specify a feature**: + - Briefly scan the current workspace to identify major features or modules. + - Provide a numbered list of 3 potential codemaps you could generate (e.g., "1. Authentication System", "2. Agent Builder", "3. Data Ingestion Pipeline"). + - Ask the user to select one or provide their own topic. + +- **If the user DOES specify a feature**: + - Proceed to Step 2 immediately. + +### 2. Research Phase +- **Search**: Use file search and grep tools to locate all files related to the requested feature. Look for frontend components, backend controllers, services, types, and database models. +- **Understand**: Read key files to understand the purpose, logic, and relationships between components. +- **Identify Critical Paths**: Determine which files are `⭐ CRITICAL` to the feature's functionality. + +### 3. Generate Codemap +Create a new file named `[feature]-codemap.md` in the **root** of the workspace (unless the user specified a different location). The file MUST include the following sections: + +#### A. File Structure (Core Files) +- List only the most essential files. + +#### B. File Structure (Comprehensive) +- Create a visual text-based tree diagram of ALL related components. +- Mark critical core files with `⭐ CRITICAL`. +- Include a short description of the purpose of each file/folder. +- **Format Example**: + ```text + frontend/src/sections/feature/ + ├── main-component.tsx # Main entry point + │ └── Orchestrates sub-components + ├── components/ + │ ├── sub-component.tsx # Renders specific UI elements ⭐ CRITICAL + │ │ └── Handles user interactions + ``` + +#### C. Architecture & Data Flow +- **Component Interaction Flow**: Describe how components talk to each other. +- **Data Flow**: Describe how data moves through the feature. +- **Mermaid Charts**: Include Mermaid diagrams for: + - User Interaction Flow + - Component Interaction Flow + - Networking/API Interaction Flow + +#### D. Code Examples +- Provide snippets of `⭐ CRITICAL` components to illustrate key logic. + +#### E. Additional Sections +- Add any other relevant sections (e.g., "State Management", "API Endpoints", "Database Schema", "Configuration") that would be useful for a developer. + +## Constraints & Best Practices +- **Length**: Aim for a comprehensive document (target at least ~500 lines if the feature complexity warrants it). +- **Location**: Save to the root workspace directory by default. +- **Style**: Be technical, precise, and exhaustive. +- **Visuals**: Use ASCII trees for file structures and Mermaid for flows. diff --git a/.agent/workflows/docker-exec.md b/.agent/workflows/docker.exec.md similarity index 100% rename from .agent/workflows/docker-exec.md rename to .agent/workflows/docker.exec.md diff --git a/.agent/workflows/docker-restart.md b/.agent/workflows/docker.restart.md similarity index 100% rename from .agent/workflows/docker-restart.md rename to .agent/workflows/docker.restart.md diff --git a/.agent/workflows/migration-apply-migration.md b/.agent/workflows/migration.apply.migration.md similarity index 100% rename from .agent/workflows/migration-apply-migration.md rename to .agent/workflows/migration.apply.migration.md diff --git a/.agent/workflows/portkit.analyze.md b/.agent/workflows/portkit.analyze.md new file mode 100644 index 0000000000..a7e645a501 --- /dev/null +++ b/.agent/workflows/portkit.analyze.md @@ -0,0 +1,190 @@ +--- +description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. +--- + +//turbo-all + +--- +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 `/speckit.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 `/speckit.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.portkit/scripts/powershell/check-prerequisites.ps1 --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, ???, ``, 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 `/speckit.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /speckit.specify with refinement", "Run /speckit.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 + +{{args}} \ No newline at end of file diff --git a/.agent/workflows/portkit.clarify.md b/.agent/workflows/portkit.clarify.md new file mode 100644 index 0000000000..76df6eb90f --- /dev/null +++ b/.agent/workflows/portkit.clarify.md @@ -0,0 +1,63 @@ +--- +description: Ask the user specifying questions to clarify scope before deep research +handoffs: + - label: Research Feature + agent: portkit.research + prompt: Clarification complete. Updates have been made to specs/[feature]/spec.md. Proceed to research. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Facilitate a "Clarification Phase" where the agent asks the user critical questions about the feature to prevent assumptions during the Research phase (e.g., "Where is the entry point?", "Is this a UI component or a backend service?"). + +## Note +This is an **Interactive** workflow. The agent should stop and wait for user input after generating the questions. + +## Outline +1. **Parse Input**: Identify Feature Name/Spec from `$ARGUMENTS`. +2. **Verify Context**: Ensure `specs/[feature]/spec.md` exists. Use `portkit.specify` if it does not. + +3. **Phase 1: Ambiguity Scan & Question Generation**: + * **Action**: Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. + * **Functional Scope**: Core user goals, success criteria, explicit inclusions/exclusions. + * **Adaptation Strategy**: Bridge adapters, omissions, replaced dependencies. + * **Dependencies**: Internal vs External, Conflict resolution (e.g. Auth, Billing), "Poison" dependencies. + * **Integration Points**: UI location, Route structure, Backend hooks. + * **Edge Cases**: Failure handling, specific constraint scenarios. + * **Generate Questions**: + * Create a prioritized queue of candidate clarification questions (maximum 5). + * Each question must be answerable with a short multiple-choice selection or a short phrase. + * Focus on "High Impact" ambiguities that would block Research or Planning. + +4. **Phase 2: Sequential Questioning Loop (Interactive)**: + * **User Interaction**: Present EXACTLY ONE question at a time. + * **Recommendation**: + * For multiple-choice, recommend the best option based on Portkit best practices (e.g. "Strip Billing"). + * Format as: `**Recommended:** Option [X] - ` + * **Integration**: + * After EACH accepted answer, immediately update the in-memory representation of the spec. + * Append to a `## Clarifications` section: `- Q: → A: `. + * Apply the clarification to the appropriate section (Scope, Strategy, etc). + * **Stop Condition**: 5 questions asked, or user signals "done". + +5. **Phase 3: Finalize Spec**: + * **Action**: Write the updated spec back to `specs/[feature]/spec.md`. + * Ensure no contradictory statements remain. + * Ensure terminology is consistent. + * **Keyword Generation**: + * Based on the spec and clarifications, append a list of **search keywords** to the Spec file (e.g., `## Research Keywords`). + * Format: `* Scan Keywords: [array of technical terms, e.g., 'Credits', 'BillingContext', 'verify_user']` + * These hints will guide the `scan-risk` and `grep` operations in the Research phase. + +6. **Completion**: + * Output: "Spec updated with clarification details and research keywords." + * **Stats**: Questions asked/answered, sections touched, keywords generated. + * **Recommendation**: Run `/portkit.research` to begin technical analysis with these new constraints. diff --git a/.agent/workflows/portkit.codemap.md b/.agent/workflows/portkit.codemap.md new file mode 100644 index 0000000000..978d3a013c --- /dev/null +++ b/.agent/workflows/portkit.codemap.md @@ -0,0 +1,80 @@ +--- +description: Research target/existing repo and create a standalone codemap of the feature +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Research target/existing repo and create a standalone codemap of the feature. + +## Note +This is an exploratory tool. It does not initiate a full porting process or modify the registry. + +## Instructions +1. **Parse Input**: Identify Target Directory/Feature and Feature Name. + * *Naming Convention*: `[YYYY-MM-DD]-[feature-name].codemap.md`. + * *Path*: `.portkit/specs/[feature-name]/[filename]`. + * If `specs/[feature-name]` does not exist, create it. + +2. **Research Phase**: + * **Goal**: Research and understand the files related to the feature deeply to create a technical analysis document codemap. Don't just list files; understand the *flow* of the codebase related to the feature + * **Action**: Explore the codebase using your preferred tools (`grep`, `find`, `read_file`). + * **Tools you have available to you (Optional but highly recommended)**: + * Use `.portkit/scripts/` if they help you move faster (e.g. `map-dependencies` for import graphs). + * Use `tree` or `Get-ChildItem` for high-level structure. + +3. **Draft Codemap**: + * **Requirement**: Be technical, precise, and exhaustive. Mark critical components clearly. + * **Format Template**: + ```markdown + # Codemap: [Feature Name] + Date: [YYYY-MM-DD] + Target: [Target Directory] + + ## 1. High-Level Architecture + [Brief description of purpose and scope] + + ## 2. File Topology/Feature Structure + (Visual Text Tree) + - src/features/X/ + - main.tsx # Entry Point ⭐ CRITICAL + - utils/ + - helper.ts # Data Processor + + ## 3. Dependency Graph + (List internal and external dependencies. Use `map-dependencies` script if helpful.) + - Internal: @/lib/auth, @/hooks/use-user + - External: react-query, zod + + ## 4. Architecture & Data Flow + * **Component Interaction**: How components talk to each other. + * **Data Flow**: How data moves (API -> Store -> UI). + + ### 4.1 User Interaction Flow (Mermaid) + ```mermaid + sequenceDiagram + User->>Component: Action + Component->>Store: Update + ``` + + ### 4.2 API/Network Flow (Mermaid) + ```mermaid + sequenceDiagram + Service->>API: Request + API-->>Service: Response + ``` + + ## 5. Critical Files Content + (Packed content or snippets of the top 3-5 most important files to provide context) + ``` + +4. **Completion**: + * Save file to `.portkit/specs/[feature-name]/[YYYY-MM-DD]-[feature-name].codemap.md`. + * Report success and full path of the new codemap you created. diff --git a/.agent/workflows/portkit.ecosystem.md b/.agent/workflows/portkit.ecosystem.md new file mode 100644 index 0000000000..d962b628a4 --- /dev/null +++ b/.agent/workflows/portkit.ecosystem.md @@ -0,0 +1,44 @@ +--- +description: Manage the Portkit Ecosystem Rules (Adaptation Constitution). View, Add, or Remove adaptation laws. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Manage the `ecosystem-rules.json` file, which serves as the "Constitution" for Portkit adaptation. It defines dependencies that must be denied (stripped) and architectural invariants that must be upheld when porting over features from other repos + +## Outline + +1. **Parse Input**: Determine intent (View, Add Rule, Remove Rule). + * Result: `action = "view" | "add" | "remove"` + +2. **Context**: Read `.portkit/ecosystem-rules.json`. + +3. **Action Execution**: + + * **If View**: + * Display the current rules in a user-friendly format (Markdown tables). + * List `denied_dependencies`, `forced_adapters`, and `architectural_invariants`. + + * **If Add Rule**: + * Prompt user for `Rule Type` (Dependency, Adapter, Invariant). + * Prompt for details (Package Name, Replacement Strategy, Reason). + * Update the JSON structure. + + * **If Remove Rule**: + * Show numbered list of rules. + * Ask user to select which one to remove. + * Update key in JSON. + +4. **Save**: write back to `.portkit/ecosystem-rules.json`. + +5. **Completion**: + * Output: "Ecosystem Rules updated." + * **Note**: "These rules will automatically be enforced by `map-dependencies` and `portkit.research` in future runs." diff --git a/.agent/workflows/portkit.generate.tests.md b/.agent/workflows/portkit.generate.tests.md new file mode 100644 index 0000000000..26523f4fe4 --- /dev/null +++ b/.agent/workflows/portkit.generate.tests.md @@ -0,0 +1,38 @@ +--- +description: Create repo-specific testing scripts to enable behavioral verification. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Create repo-specific testing scripts to enable behavioral verification of the feature. + +## Note +These tests are crucial for Phase 4 (Verification). Without them, verification relies solely on build checks, which may miss runtime issues. + +## Outline +1. **Parse Input**: Identify Feature Name and Technology (e.g., Next.js, Python). +2. **Analyze Context**: + * Check `package.json` for `playwright`, `cypress`, `jest`. + * Check `pyproject.toml` or `requirements.txt` for `pytest`. + +3. **Strategy**: + * **Frontend**: Prefer Playwright E2E for generic feature verification. + * **Backend**: Prefer Pytest integration tests. + +4. **Scaffold Test**: + * **Create File**: `tests/portkit_[feature].spec.ts` (or `test_portkit_[feature].py`). + * **Draft Content**: + * Import `spec.md` requirements (as comments). + * Generate standard boilerplate (Login -> Navigate to Page -> Assert Element Visible). + * *Note*: Use best-guess selectors based on `research.md` or `tasks.md` file modifications. + +5. **Completion**: + * Output: "Test scaffold created at `tests/portkit_[feature].spec.ts`. Run with `npx playwright test ...`." diff --git a/.agent/workflows/portkit.implement.md b/.agent/workflows/portkit.implement.md new file mode 100644 index 0000000000..9e19917b3f --- /dev/null +++ b/.agent/workflows/portkit.implement.md @@ -0,0 +1,50 @@ +--- +description: Execute the Portkit implementation tasks. +handoffs: + - label: Verify Implementation + agent: portkit.verify + prompt: Implementation complete. Proceed to verification. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Execute the atomic tasks defined in `tasks.md` to implement the feature, including sanitation, morphing, and integration. + +## Note +Strict adherence to `tasks.md` is required. Do not improvise new architecture during implementation without updating the plan. + +## Outline +1. **Parse Input**: Identify Feature Name. +2. **Verify Context**: Ensure `tasks.md` and `implementation_plan.md` exist. + +3. **Gate Check (Checklists)**: + * Scan `implementation_plan.md` (or `checklists/requirements_check.md`). + * If any unchecked items in the "Requirements Checklist", **STOP** and warn user. + * *Portkit Specific*: Verify `research.md` confirms Upstream Ref is valid. + +4. **Execution Loop**: + * Read `tasks.md`. + * Identify next unchecked task `[ ] T###`. + * **Execute**: + * **If Script**: Run the specified `uv run ...` or `npx ts-node ...` command. + * **If Code**: Open the file, apply changes (Shim, Morph, Inject). + * **If Manual**: Ask user or skip (if marked optional). + * **Mark Complete**: Update `tasks.md` entry to `[x] T###`. + * *Progress*: Report back to user after every Phase completion. + +5. **Error Handling**: + * If a task fails (script error, compile error): + * Attempt self-correction (1 retry). + * If still failing, **Stop** and ask User for intervention. Do not blindly leverage hallucinations. + +6. **Completion**: + * When all tasks are `[x]`, run a quick `verify-project` check (optional). + * **Recommendation**: Suggest the user runs `/portkit.verify` to audit the changes. diff --git a/.agent/workflows/portkit.init.md b/.agent/workflows/portkit.init.md new file mode 100644 index 0000000000..63e003c6df --- /dev/null +++ b/.agent/workflows/portkit.init.md @@ -0,0 +1,46 @@ +--- +description: Entry point for Portkit. Initialize agent memory/constitution (`agent.md`, `gemini.md`) to be aware of Portkit structure. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Initialize Portkit for agent memory files such as `agent.md`, `gemini.md`, `AGENTS.md`, etc. and the repository structure to support the Portkit workflow. You will find these files or create them if missing in the root of the repository. + +## Note +This should be run once when portkit is installed or initialized in a directory or when the agent is amnesic to ensure it understands the Portkit conventions. If it is run multiple times, ensure to ask the user if they want to reinitialize the Portkit structure and/or update the workflow files by copying the contents of the `.portkit/workflows/[environment folder]` directory from the Portkit installation directory. + +## Outline +1. **Welcome**: Acknowledge that this is the **Portkit** initialization workflow (Speckit for Upstream Sync). +2. **Verify Structure**: Check for existence of core Portkit files: + * `.portkit/README.md` + * `.portkit/addon-features-registry/feature-registry.json` + * `.portkit/ecosystem-rules.json` (Constitution) + * `.portkit/scripts/` (Ensure contents exist) + * `.portkit/templates/` (Ensure spec-template, etc. exist) + * **Action**: + * Run `.portkit/scripts/powershell/init-portkit.ps1` or bash equivalent to ensure registry exists and portkit files are setup correctly. + +3. **Update Gitignore**: + * Ensure `.portkit-cache/` is added to `.gitignore`. + +4. **Update Agent Memory/Constitution**: + * Locate the active memory file (e.g., `.agent/AGENTS.md`, `[repo root]/Claude.md`, or `[repo root]/AGENTS.md`or create if missing). + * **Action**: Append or Update a standard `## Portkit Awareness` section. + * **Content to Inject**: + ```markdown + ## Portkit Awareness + **This repo uses Portkit and is found at `.portkit/` folder. Portkit specific scripts are found at `.portkit/scripts/` folder.** + * To port a **NEW** feature from upstream: + * Run: `/portkit.specify "Description of the feature"` + * To lock **EXISTING** code to protect it from overwrites: + * Run: `/portkit.tag.features "Description of the feature"` + * To just **EXPLORE** the upstream codebase:: + * Run: `/portkit.codemap "Description of the feature"` \ No newline at end of file diff --git a/.agent/workflows/portkit.plan.md b/.agent/workflows/portkit.plan.md new file mode 100644 index 0000000000..b22219eae5 --- /dev/null +++ b/.agent/workflows/portkit.plan.md @@ -0,0 +1,61 @@ +--- +description: Create component morphing strategy and implementation plan. Generates `implementation_plan.md`. +handoffs: + - label: Decompose Tasks + agent: portkit.tasks + prompt: Plan approved at `specs/[feature]/implementation_plan.md`. Decompose into tasks. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Create a detailed Component Morphing strategy and Implementation Plan based on the Research artifacts. + +## Note +This is the "Architect and Research and Reiterate Planning" phase. Critical decisions about "Poison" code removal and Shim creation happen here. + +Additionally when /portkit.plan is run multiple times, follow a Plan ---> Research ---> Reinterate Plan cycle until user is satisfied with the plan. + +## Outline +1. **Parse Input**: Identify Feature Name. +2. **Verify Context**: Ensure `research.md` (and `spec.md`) exists. +3. **Constitution Check**: + * Review `research.md` against project constraints. + * *Example Rule*: "No Direct Upstream Overwrites without `sanitize-upstream`." + * *Example Rule*: "All Custom Logic must be preserved via `extract-region`." + +4. **Strategy Formulation (The Core)**: + * **Component Morphing**: For each UI component in the Blast Radius: + * Define: **Source** (Upstream File) -> **Diff** (What changed) -> **Strategy** (Extract -> Nuke -> Paste -> Inject). + * **Bridge Adapters** (Shims): + * Identify "Poison" imports (Billing, Auth, Analytics). + * Define replacement: `import { auth } from 'upstream'` -> `import { auth } from '@/lib/auth-shim'`. + +5. **Draft Implementation Plan**: + * Read template: `.portkit/templates/implementation_plan.md`. + * **Fill Sections**: + * `## Strategy`: The high-level approach. + * `## Component Morphing`: The specific per-file table. + * `## Bridge Adapters`: List of shims to build. + * `## Checklist`: + * Generate "Unit Tests for Requirements" (adapted from Speckit). + * Example: "- [ ] Auth Shim handles 'Guest' user correctly." + * Example: "- [ ] Styling matches Local Theme (Dark Mode)." + * Write to: `.portkit/specs/[feature]/implementation_plan.md`. + + +6. **Review & Refine**: + * Ask user to review the Morph Strategy. + * *Example*: If a "Complex Merge" is identified, confirm the strategy is feasible. + * **Requirement**: Review plan.md document and append utilize [NEEDS CLARIFICATION] tags for plan steps that require more information and research. + +7. **Completion**: + * Output plan location and ask user to review it. + * **Recommendation**: Only suggest the user runs `/portkit.tasks` to decompose this plan into actionable steps if the plan is complete and ready to be executed. diff --git a/.agent/workflows/portkit.research.md b/.agent/workflows/portkit.research.md new file mode 100644 index 0000000000..aadf7c0b30 --- /dev/null +++ b/.agent/workflows/portkit.research.md @@ -0,0 +1,73 @@ +--- +description: Research upstream feature structure and dependencies. Generates `research.md`. +handoffs: + - label: Plan Implementation + agent: portkit.plan + prompt: Research complete. Blast radius defined in `specs/[feature]/research.md`. Start planning. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Perform deep technical analysis of the upstream feature and its dependencies ("Blast Radius") to inform creation of the implementation plan at later stages. + +## Note +Use the provided scripts to handle large files. Avoid manual reading of massive upstream directories to conserve context. + +## Outline +1. **Parse Input**: Identify Feature Name/Spec from `$ARGUMENTS`. +2. **Verify Context**: Ensure `specs/[feature]/spec.md` exists. + +3. **Phase 1: Research and Discovery**: + * **Goals**: + * You are mandated to begin comprehensive discovery and research of the upstream codebase and identify the entry points, code modules, and dependencies.Use scripts and commands to research the codebase in `.portkit-cache` to locate the feature code and its modules in the upstream codebase. + * Identify "Risk Zones" immediately utilizing portkit scripts and 'ecosystem-rules.json'. + * **Available Tools** (Located in `.portkit/scripts/`): + * `fetch-upstream.py`: Clone/Fetch remote repo to `.portkit-cache`. + * `scan-risk.py`: Detects banned dependencies and risky keywords using `ecosystem-rules.json`. + * `map-dependencies`: Analyze file imports/exports (Choose TS or PY version). + * `smart-diff`: Semantic comparison of Upstream vs Local. + * **Recommended Action**: + * Run `fetch-upstream` to get source code. + +4. **Phase 2: Initial Scan & Discovery**: + * **Goal**: Locate the feature code and identify "Risk Zones" immediately. + * **Mandate**: Use `inspect-upstream.py` to navigate and list out files in the upstream repo to locate the feature code and identify "Risk Zones" immediately. **DO INSPECT FILES MANUALLY** by reading the files to identify the feature code and its modules in the upstream codebase. + * **Keyword Sources**: Check `specs/[feature]/spec.md` for `## Research Keywords`. + * **Actions**: + * **Locate Components**: Use `uv run .portkit/scripts/python/inspect-upstream.py search "keyword1,keyword2" [path]` to find files containing key terms. + * *Hint*: Start with root path `.` or a broad folder like `backend` or `frontend`. + * **Visualize Structure**: Use `uv run .portkit/scripts/python/inspect-upstream.py ls -r [folder]` to see the file tree of identified components. + * **Risk Scan**: Run `uv run .portkit/scripts/python/scan-risk.py --target [feature_folder]` to check for banned dependencies. + * **Blast Radius**: Run `uv run .portkit/scripts/python/map-dependencies.py` on the entry file(s) to see what else it touches. + +5. **Phase 3: Semantic Analysis (The "Codemap")**: + * **Goal**: Generate a comprehensive codemap of the feature *before* we touch it. + * **Mandate**: Use `smart-diff.py` for all difference checking. **DO NOT** read files manually to diff them. + * **Constraint**: **NEVER** run `smart-diff` on the root directory. You **MUST** target specific feature folders or subdirectories identified in Phase 2 (e.g. `backend/core/sandbox` or `frontend/src/features/computer`). Use `-r` for recursive folder comparison. + * **Analyze**: + * **File Structure**: Tree of upstream files involved. + * **Critical Paths**: Identify "Load Bearing" components (Auth, Database, State). + * **Data Flow**: How does data move? (Mermaid Diagram required). + * **Blast Radius**: Identify local files that will be touched/broken if the upstream feature is directly implemented without adaptation. + +6. **Phase 4: Synthesize Report**: + * Read template: `.portkit/templates/research.md`. + * **Populate Sections**: + * `## Codemap`: The detailed tree and Mermaid flow. + * `## Semantic Diff`: Summary of script output (e.g. "Signature changed for `User`"). + * `## Specifications & Limitations`: + * "Upstream uses `NextAuth`. We use `Supabase`. (Conflict)" + * "Upstream uses `Tailwind v4`. We use `v3`. (Shim needed)." + * Write to: `.portkit/specs/[feature]/research.md`. + +7. **Completion**: + * Output summary of the Research. + * **Recommendation**: Suggest the user runs `/portkit.plan` to proceed with planning the implementation strategy. diff --git a/.agent/workflows/portkit.specify.md b/.agent/workflows/portkit.specify.md new file mode 100644 index 0000000000..12972e5ad6 --- /dev/null +++ b/.agent/workflows/portkit.specify.md @@ -0,0 +1,72 @@ +--- +description: Specify a feature to port using Portkit. Creates `spec.md` with robust ambiguity checking. +handoffs: + - label: Research Feature + agent: portkit.research + prompt: The spec is ready at `specs/[feature]/spec.md`. Begin research. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Define a clear, unambiguous specification for the feature to be ported, including scope and initial assumptions. + +## Note +Ambiguity here leads to failure later. Ensure checking for existing registry conflicts before proceeding. + +## Outline +The text the user provided in `$ARGUMENTS` is the feature description. + +1. **Generate Feature Short Name**: + * Analyze description. Create a concise `kebab-case` name (e.g., `user-auth`, `fix-payment-bug`). + * *Constraint*: 2-4 words, descriptive. + +2. **Environment Check (No Forced Branching)**: + * Check if directory `.portkit/specs/[feature-name]/` already exists. + * **Interactive Decision**: + * If it exists: Ask user "Spec directory `[feature-name]` exists. Overwrite? (y/n)". + * If 'n', abort or ask for new name. + * If it doesn't exist: Proceed. + * *Note*: Unlike Speckit, we do NOT forcibly create a Git branch here. We work in the main workspace, relying on the user's git workflow or later stages to handle branching. + +3. **Draft Specification**: + * Read template: `.portkit/templates/spec-template.md`. + * **Analysis Loop**: + * Extract: Actors, Actions, Data, Constraints from inputs. + * Fill Mandatory Sections: Functional Requirements, Success Criteria (Measurable/Testable). + * *Defaulting*: Use industry standards (e.g., Standard Auth, Cloudflare Images) where details are missing but obvious. + * **Clarification (Ambiguity Detection)**: + * Identify critical gaps (Scope, Security, UX). + * **Limit**: Max 3 `[NEEDS CLARIFICATION]` tags. + * If <3 clarifications needed, proceed to fill them with best-guess defaults and mark as "Assumption". + +4. **Write Initial Spec**: + * Ensure directory `.portkit/specs/[feature-name]/` exists. + * Write file `.portkit/specs/[feature-name]/spec.md`. + +5. **Quality Validation Loop** (The "Speckit Standard"): + * **Goal**: Ensure spec is "Builder-Ready". + * **Action**: Create temporary checklist `requirements_check.md` (in memory or temp file). + * **Checklist Items**: + * [ ] No `[NEEDS CLARIFICATION]` remains (resolve them if user answers now, or note them). + * [ ] Requirements are Testable. + * [ ] Success criteria are Technology-Agnostic. + * [ ] Bridge Adapters defined (if obvious from prompt, e.g., "Use our Auth"). + * **Self-Correction**: If validation fails, attempt to fix the `spec.md` immediately using context. + +6. **Registry Check**: + * Read `.portkit/addon-features-registry/feature-registry.json`. + * Warn if `[feature-name]` conflicts with an existing registry key. + +7. **Completion**: + * Output: "Spec created at `.portkit/specs/[feature-name]/spec.md`". + * **Recommendation**: + * If the spec contains `[NEEDS CLARIFICATION]`: Recommend the user to run `/portkit.clarify` to resolve ambiguities interactively. + * Otherwise: Recommend the user to run `/portkit.research` to begin technical analysis. diff --git a/.agent/workflows/portkit.tag.features.md b/.agent/workflows/portkit.tag.features.md new file mode 100644 index 0000000000..888c30c8eb --- /dev/null +++ b/.agent/workflows/portkit.tag.features.md @@ -0,0 +1,46 @@ +--- +description: Retroactively add `// feature-start` tags to existing code. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Retroactively apply Portkit tracking tags (`// feature-start`) to existing code to bring it under registry control. + +## Note +Essential for "locking" pre-existing features so they aren't accidentally overwritten by future ports. + +## Outline +1. **Parse Input**: Identify Feature Name and Target Files (or directory scope). +2. **Context**: Read `spec.md` or `research.md` if available to understand file scope. + +3. **Tagging Logic**: + * **Goal**: Wrap specific code blocks or whole files with Portkit tracking tags. + * **Format**: `// feature-start: [name]` ... `// feature-end: [name]`. + * **Action**: + * For **Whole Files**: Add tags at top/bottom of file. + * For **Partial Blocks**: + * Ask user to identify line ranges or functions. + * *OR* Use `grep` to find specific function definitions mentioned in input. + * Apply the edits. + +4. **Blast Radius Tagging (Recursive Protection)**: + * **Goal**: A feature is not just its definition; it is also its *usage*. + * **Action**: + * If the user specified a specific function or class (e.g., `getApiUrl`): + * Run `grep` or `smart-diff-feature` to find ALL files that import/call this function. + * **Interactive Decision**: Ask user "Found X files using [Function]. Tag these usages too? (y/n)". + * If 'y': Go to those files and wrap the *specific call lines* with `// feature-start: [name]` tags. + * **Why?**: This prevents "Spooky Action at a Distance" where a port overwrites a file that *uses* your critical feature, breaking the link. + +4. **Registry Sync**: + * After tagging, **Recommendation**: Suggest the user runs `/portkit.update.registry` to index the new tags. + +5. **Completion**: Output list of tagged files. diff --git a/.agent/workflows/portkit.tasks.md b/.agent/workflows/portkit.tasks.md new file mode 100644 index 0000000000..86815fcf3f --- /dev/null +++ b/.agent/workflows/portkit.tasks.md @@ -0,0 +1,74 @@ +--- +description: Decompose Portkit strategies into atomic, dependency-ordered tasks. Generates `tasks.md`. +handoffs: + - label: Implement Feature + agent: portkit.implement + prompt: Tasks ready at `specs/[feature]/tasks.md`. Begin code implementation. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Decompose the Implementation Plan into atomic, dependency-ordered tasks executable by a builder agent. + +## Note +Tasks must be granular enough (one file per task ideally) to prevent the downstream implementation agents from getting overwhelmed. + +## Outline +1. **Parse Input**: Identify Feature Name. +2. **Verify Context**: Ensure `implementation_plan.md` exists. Use absolute paths. +3. **Task Generation Logic**: + * **Goal**: Translate "Morph Strategies" and "Bridge Adapters" into executable `T###` tasks. + * **Critical Constraint**: Tasks MUST be atomic. An agent should be able to execute one task without asking for clarification. + * **Registry Enforcement**: Any task that creates a **new file** MUST include an instruction to add `// feature-start: [name]` and `// feature-end: [name]` tags to that file. + +4. **Task Format Rules (REQUIRED)**: + * Every task MUST strictly follow this format: + ```text + - [ ] [TaskID] [Phase] [P?] Description with file path/script + ``` + * **Components**: + * `[TaskID]`: Sequential (T001, T002...). + * `[Phase]`: The execution phase (Ingest, Adapt, Morph, Verify). + * `[P?]`: Include `[P]` ONLY if task is parallelizable (no dependencies on preceding incomplete tasks). + * **Description**: Clear action with exact file path or script command. + + * **Examples**: + * ✅ `- [ ] T001 [Ingest] Run fetch-upstream script for tag v1.0` + * ✅ `- [ ] T005 [Adapt] [P] Create shim for @/lib/auth at src/lib/auth-shim.ts` + * ✅ `- [ ] T010 [Morph] [P] Run extract-region script on src/components/Sidebar.tsx` + * ❌ `- [ ] Create auth shim` (Missing ID, Phase, Path) + +5. **Draft `tasks.md`**: + * **Phase 1: Ingestion (Setup)**: + * `- [ ] T001 [Ingest] Fetch upstream dependencies (Recommend: fetch-upstream script)` + * `- [ ] T002 [Ingest] Sanitize code (Recommend: sanitize-upstream script)` + + * **Phase 2: Adapters (Foundational)**: + * Blocking tasks. Create usage of "Bridge Adapters" defined in plan. + * Example: `- [ ] T003 [Adapt] Create Auth Shim at ...` + + * **Phase 3: Integration (Morphing)**: + * Per-component tasks from the Plan's "Morph Strategy". + * *Parallelism*: Distinct components are usually `[P]`. + * *Tooling*: Recommend `extract-region` for complex merges. + * *Agent Discretion*: If a file is small, Manual Edit is fine. + + * **Phase 4: Verification**: + * `- [ ] T900 [Verify] Run verify-project.py` + * `- [ ] T901 [Verify] Run portkit.verify workflow` + +6. **Output**: + * Write to: `.portkit/specs/[feature]/tasks.md`. + * *Self-Correction*: Ensure no tasks are ambiguous. Every task must mention a specific file or script. + +7. **Completion**: + * Report task count. + * **Recommendation**: Suggest the user runs `/portkit.implement` to begin code modification. diff --git a/.agent/workflows/portkit.update.registry.md b/.agent/workflows/portkit.update.registry.md new file mode 100644 index 0000000000..330936ac05 --- /dev/null +++ b/.agent/workflows/portkit.update.registry.md @@ -0,0 +1,45 @@ +--- +description: Update `feature-registry.json` with the latest feature details or an existing feature's details based on user description +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Scan the codebase for feature tags and update the `feature-registry.json` source of truth. + +## Note +This acts as the "Commit" step for Portkit. Until this runs, the system is unaware of the new feature boundaries. + +## Outline +1. **Parse Input**: Identify Feature Name (optional) or "Scan All". +2. **Context**: Read `.portkit/addon-features-registry/feature-registry.json`. + +3. **Execution (Deep Scan)**: + * **Goal**: Lock the current state of feature files. + * **Run Script**: + * Python: `uv run scripts/python/update-registry.py --update` + * TypeScript: `npx tsx scripts/typescript/update-registry.ts --update` + * **Flags**: + * `--update`: Commits changes to `feature-registry.json`. Without this, it runs in "Dry Run" mode. + * `--audit`: Checks for files that have been modified but are NOT tagged (Safety Net). + * `--folder [path]`: Limits the scan to a specific directory (Performance Optimization). + * **Logic (Mental Model)**: + * Script scans for `// feature-start: [Name]` tags. + * Calculates checksums/paths of tagged regions. + * Updates the JSON registry file entries. + +4. **Verification**: + * Reload `feature-registry.json`. + * Confirm the entry for `[feature-name]` has updated `last_sync` timestamp and file list. + +6. **Completion**: + * Output: "Registry updated for [Feature]. Lockfile is current." + * Stats: "Tracking X files, Y lines of code." + * **Recommendation**: Porting process complete. Suggest the user runs `/portkit.specify` if they wish to start a new feature port. diff --git a/.agent/workflows/portkit.verify.md b/.agent/workflows/portkit.verify.md new file mode 100644 index 0000000000..e9ed17f8db --- /dev/null +++ b/.agent/workflows/portkit.verify.md @@ -0,0 +1,59 @@ +--- +description: Verify the ported feature via build, lint, and behavioral tests. Generates `review.md`. +handoffs: + - label: Update Registry + agent: portkit.update.registry + prompt: Verification passed. Update the registry to lock this feature. +--- + +//turbo-all + +## User Input +```text +$ARGUMENTS +``` + +You **MUST** consider the user input before proceeding (if not empty). + +## Goal +Validate the implemented feature via static analysis (lint/build) and behavioral testing. + +## Note +Do not proceed to Registry Update until this phase passes. A broken feature should not be locked into the registry. + +## Outline +1. **Parse Input**: Identify Feature Name. +2. **Verify Context**: Ensure `tasks.md` marked complete. + +3. **Phase 1: Static Analysis (The Audit)**: + * **Registry Check**: Does `feature-registry.json` exist? + * **Lint**: Run `npm run lint` (or project equivalent). + * **Build**: (assuming there is a docker files and docker compose files) + * Frontend: `docker compose up -d --build --no-deps frontend` (Ensures build passes in container). + * Backend: `docker compose up -d --build --no-deps backend` (if backend changes). + * **Artifact Consistency**: Check if `spec.md` requirements match `tasks.md` completion. + +4. **Phase 2: Behavioral Verification**: + * **Goal**: Ensure feature actually works. + * **Action**: + * Ask user: "Do we have a specific test script?" + * If yes: Run `npx playwright test tests/feature.spec.ts`. + * If no: Suggest creating one via `/portkit.generate.tests` OR run a manual walkthrough plan. + +4. **Registry Coverage Audit (The Safety Net)**: + * **Action**: `uv run scripts/python/update-registry.py --audit` + * **Goal**: Detect if any *modified* or *new* files are missing `// feature-start` tags. + * **Logic**: + * If it returns "success": Pass. + * If it returns "warning" with a list of "untracked_files": + * **STOP**. You have created orphaned code. + * **Fix**: Go back and add tags to those files. + +5. **Report Generation**: + * Compile findings into `review.md`. + * Verdict: `PASS` / `FAIL`. + * Write to: `.portkit/specs/[feature]/review.md`. + +6. **Completion**: + * If **PASS**: Suggest the user runs `/portkit.update.registry` to lock the feature. + * If **FAIL**: Suggest potential remediation steps or suggest to the user to run `/portkit.implement` again to fix bugs. diff --git a/.agent/workflows/recent-docs.md b/.agent/workflows/recent.docs.md similarity index 100% rename from .agent/workflows/recent-docs.md rename to .agent/workflows/recent.docs.md diff --git a/.agent/workflows/recent-files.md b/.agent/workflows/recent.files.md similarity index 100% rename from .agent/workflows/recent-files.md rename to .agent/workflows/recent.files.md diff --git a/.agent/workflows/verify-docker-build.md b/.agent/workflows/verify.docker.build.md similarity index 100% rename from .agent/workflows/verify-docker-build.md rename to .agent/workflows/verify.docker.build.md diff --git a/.agent/workflows/analyze.md b/.claude/commands/analyze.md similarity index 94% rename from .agent/workflows/analyze.md rename to .claude/commands/analyze.md index 48c76c537f..542a3dec1e 100644 --- a/.agent/workflows/analyze.md +++ b/.claude/commands/analyze.md @@ -2,12 +2,6 @@ description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. --- -//turbo-all - ---- -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 @@ -30,14 +24,14 @@ Identify inconsistencies, duplications, ambiguities, and underspecified items ac ### 1. Initialize Analysis Context -Run `.specify/scripts/powershell/check-prerequisites.ps1 --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: +Run `.specify/scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks` 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"). +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) @@ -187,4 +181,4 @@ Ask the user: "Would you like me to suggest concrete remediation edits for the t ## Context -{{args}} \ No newline at end of file +$ARGUMENTS diff --git a/.claude/commands/checklist.md b/.claude/commands/checklist.md new file mode 100644 index 0000000000..b15f9160db --- /dev/null +++ b/.claude/commands/checklist.md @@ -0,0 +1,294 @@ +--- +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/powershell/check-prerequisites.ps1 -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 `/speckit.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### ` 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 `/speckit.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?" diff --git a/.claude/commands/clarify.md b/.claude/commands/clarify.md new file mode 100644 index 0000000000..0678e92151 --- /dev/null +++ b/.claude/commands/clarify.md @@ -0,0 +1,181 @@ +--- +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: speckit.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 `/speckit.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/powershell/check-prerequisites.ps1 -Json -PathsOnly` 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 `/speckit.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] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |