ac-framework 1.5.0 → 1.7.0

package/framework/.claude/skills/requirement-checklist/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: requirement-checklist
+description: Generate comprehensive checklists to validate requirements quality (Unit Tests for Specs). Critically examine the spec for clarity, completeness, and consistency before implementation starts.
+---
+
+# Requirement Checklist Generation
+
+## Overview
+
+Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain.
+
+**NOT for verification/testing implementation**:
+*   ❌ 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)
+
+## Execution Steps
+
+1.  **Setup**:
+    *   Parse feature directory and available docs list.
+    *   Identify the target feature spec (`spec.md`, `plan.md`, `tasks.md`).
+
+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
+    *   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.
+
+3.  **Generate checklist - Create "Unit Tests for Requirements"**:
+    *   Create a checklist file in the feature directory (e.g., `checklists/[domain].md`).
+    *   Format: `[domain].md` (e.g., `ux.md`, `api.md`, `security.md`).
+    *   Number items sequentially starting from CHK001.
+    *   Each run creates a NEW file (never overwrites existing checklists unless explicitly told).
+
+    **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**:
+    *   Requirement Completeness
+    *   Requirement Clarity
+    *   Requirement Consistency
+    *   Acceptance Criteria Quality
+    *   Scenario Coverage
+    *   Edge Case Coverage
+    *   Non-Functional Requirements
+    *   Dependencies & Assumptions
+    *   Ambiguities & Conflicts
+
+4.  **Structure Reference**:
+    *   Generate the checklist following a markdown template: Title, Purpose, Category Headings, `##` sections, `- [ ] CHK### <requirement item>` lines.
+
+5.  **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, and valid user must-haves.
+
+## Checklist Item Guidelines
+
+**Example Checklist Items**:
+
+*   **UX**: "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]"
+*   **API**: "Are error response formats specified for all failure scenarios? [Completeness]"
+*   **Performance**: "Are performance requirements quantified with specific metrics? [Clarity]"
+*   **Security**: "Are authentication requirements specified for all protected resources? [Coverage]"
+
+**Avoid Implementation Tests**:
+*   ❌ "Verify landing page displays 3 episode cards"
+*   ❌ "Test hover states work correctly on desktop"
+*   ❌ "Confirm logo click navigates to home page"
+
+**Use Quality Checks**:
+*   ✅ "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]

package/framework/.claude/skills/research-retrieval/SKILL.md

@@ -0,0 +1,357 @@
+---
+name: research-retrieval
+description: Search external documentation (web pages, API docs, papers) and generate useful summaries for development. Use when investigating new technologies, understanding third-party APIs, researching best practices, or gathering information for technical decisions. Reduces hallucinations and expands agent knowledge.
+license: MIT
+metadata:
+  author: AC Framework
+  version: "1.0"
+---
+
+# Research & Retrieval
+
+External knowledge search, documentation retrieval, and synthesis for informed development decisions.
+
+## When to Use This Skill
+
+Use this skill when:
+- Investigating new technologies, libraries, or frameworks
+- Understanding third-party APIs and their capabilities
+- Researching best practices for a specific problem
+- Gathering information for architecture decisions
+- Need to verify facts or current information
+- Exploring solutions to unfamiliar problems
+
+## Instructions
+
+### Step 1: Define Research Goals
+
+1. **Clarify what you need to know**:
+   - Specific technical question
+   - Comparison of technologies
+   - Implementation approach
+   - Best practices
+
+2. **Identify sources**:
+   - Official documentation
+   - API references
+   - Technical blogs
+   - Research papers
+   - GitHub repositories
+   - Stack Overflow
+
+3. **Set scope boundaries**:
+   - Time period (recent vs. historical)
+   - Version specificity
+   - Language/framework constraints
+
+### Step 2: Search and Retrieve
+
+**Official Documentation**:
+```
+Priority sources:
+1. Official docs (docs.{service}.com)
+2. API reference
+3. Getting started guides
+4. Best practices
+5. Changelog/release notes
+```
+
+**Technical Blogs & Articles**:
+```
+Quality indicators:
+- Recent publication date
+- Author expertise/credentials
+- Code examples included
+- Community engagement
+- Updated for current versions
+```
+
+**Research Papers** (for advanced topics):
+```
+Use when:
+- Novel algorithms needed
+- Performance optimizations
+- Academic foundations
+- Cutting-edge techniques
+```
+
+**GitHub Repositories**:
+```
+Evaluate by:
+- Stars/forks (popularity)
+- Recent commits (maintenance)
+- Issue resolution (support)
+- Documentation quality
+- Test coverage
+```
+
+### Step 3: Evaluate Sources
+
+**Credibility Checklist**:
+- [ ] Authoritative source (official > third-party)
+- [ ] Up-to-date information
+- [ ] Well-explained with examples
+- [ ] Community-validated (comments, issues)
+- [ ] Version compatibility noted
+
+**Red Flags**:
+- Outdated documentation
+- Unexplained "magic" solutions
+- No code examples
+- Deprecated approaches
+- Unsupported claims
+
+### Step 4: Extract Key Information
+
+For each relevant source, extract:
+
+```markdown
+## Source: [Title/URL]
+
+**Relevance**: [High/Medium/Low]
+**Date**: [Publication date]
+**Version**: [Software version, if applicable]
+
+### Key Points
+
+1. [Important finding 1]
+2. [Important finding 2]
+3. [Important finding 3]
+
+### Code Examples
+
+\`\`\`[language]
+// Relevant code snippet
+\`\`\`
+
+### Warnings/Caveats
+
+- [Known issues or limitations]
+- [Breaking changes]
+- [Performance considerations]
+
+### References
+
+- [Link 1]
+- [Link 2]
+```
+
+### Step 5: Synthesize Findings
+
+**Compare approaches**:
+
+```markdown
+## Technology Comparison: [Topic]
+
+### Option A: [Technology A]
+
+**Pros**:
+- Advantage 1
+- Advantage 2
+
+**Cons**:
+- Disadvantage 1
+- Disadvantage 2
+
+**Best for**: [Use cases]
+
+### Option B: [Technology B]
+
+**Pros**:
+- Advantage 1
+- Advantage 2
+
+**Cons**:
+- Disadvantage 1
+- Disadvantage 2
+
+**Best for**: [Use cases]
+
+### Recommendation
+
+[Your recommendation with justification]
+```
+
+**Synthesize best practices**:
+
+```markdown
+## Best Practices: [Topic]
+
+Based on [N] sources, consensus on:
+
+### Do's
+1. [Recommended approach 1]
+2. [Recommended approach 2]
+
+### Don'ts
+1. [Anti-pattern 1]
+2. [Anti-pattern 2]
+
+### Trade-offs
+- [Decision point]: [Option A] vs [Option B]
+  - Choose A when: [conditions]
+  - Choose B when: [conditions]
+```
+
+### Step 6: Generate Actionable Steps
+
+Convert research into implementation steps:
+
+```markdown
+## Implementation Guide: [Topic]
+
+### Prerequisites
+- [Requirement 1]
+- [Requirement 2]
+
+### Step-by-Step
+
+1. **Setup**
+   - [Action 1]
+   - [Action 2]
+
+2. **Configuration**
+   - [Action 3]
+   - [Action 4]
+
+3. **Implementation**
+   - [Action 5]
+   - [Action 6]
+
+4. **Testing**
+   - [Action 7]
+
+### Common Pitfalls
+- [Pitfall 1] → [Solution]
+- [Pitfall 2] → [Solution]
+```
+
+### Step 7: Store for Reuse
+
+Save findings in `references/` directory:
+
+```
+references/
+├── README.md (index of all references)
+├── api/
+│   ├── stripe-api-2024-01.md
+│   └── openai-api-best-practices.md
+├── libraries/
+│   ├── react-server-components.md
+│   └── state-management-comparison.md
+└── patterns/
+    ├── authentication-patterns.md
+    └── caching-strategies.md
+```
+
+### Step 8: Link to OpenSpec
+
+Reference research in specs:
+
+```markdown
+## Specification: [Feature]
+
+### Research References
+
+- [Authentication Patterns](../references/patterns/authentication-patterns.md)
+- [Stripe API Integration](../references/api/stripe-api-2024-01.md)
+
+### Decisions Based on Research
+
+1. **Use JWT for authentication**
+   - Rationale: [Summary of research findings]
+   - Sources: [Links to references]
+
+2. **Implement Redis caching**
+   - Rationale: [Performance benchmarks from research]
+   - Sources: [Links to references]
+```
+
+## Output Format
+
+After research is complete:
+
+```
+## Research Summary: [Topic]
+
+**Sources Consulted**: [N]
+**Date**: [Research date]
+**Confidence**: [High/Medium/Low]
+
+### Executive Summary
+
+[2-3 sentence overview of findings]
+
+### Key Findings
+
+1. [Finding 1 with source]
+2. [Finding 2 with source]
+3. [Finding 3 with source]
+
+### Recommendations
+
+1. [Actionable recommendation 1]
+2. [Actionable recommendation 2]
+
+### Implementation Steps
+
+[Step-by-step guide based on research]
+
+### References Stored
+
+- references/[category]/[filename].md
+- [Link to full research document]
+
+### Uncertainties/Gaps
+
+- [What still needs investigation]
+- [Questions that remain unanswered]
+```
+
+## Guardrails
+
+- **Verify critical information** - Cross-reference multiple sources
+- **Check publication dates** - Avoid outdated information
+- **Prefer official docs** - Authoritative over anecdotal
+- **Acknowledge uncertainty** - Be clear when information is incomplete
+- **Document sources** - Always cite where information came from
+- **Focus on actionable info** - Avoid research rabbit holes
+
+## Search Strategies
+
+**Error Messages**:
+```
+"[exact error message]" + [technology name]
+```
+
+**Feature Comparisons**:
+```
+[technology A] vs [technology B] 2024
+[technology A] alternative
+```
+
+**Best Practices**:
+```
+[technology] best practices
+[technology] common pitfalls
+```
+
+**Implementation Guides**:
+```
+[technology] getting started tutorial
+[technology] example project
+```
+
+## Requirements
+
+- Web search capability
+- Access to documentation sites
+- Ability to evaluate source credibility
+- Understanding of the domain being researched
+
+## See Also
+
+- `context-synthesizer` - Integrate research into project context
+- `spec-clarification` - Use research to clarify requirements
+- `documentation` - Document findings
+- `brainstorming` - Generate ideas based on research

package/framework/.claude/skills/spec-analysis/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: spec-analysis
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md. Identifying inconsistencies, duplications, ambiguities, and underspecified items.
+---
+
+# Specification & Planning Analysis
+
+## Overview
+
+Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation.
+
+**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan.
+
+**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable**.
+
+## Execution Steps
+
+1.  **Initialize Analysis Context**:
+    *   Load `FEATURE_DIR/spec.md` (or `specs/spec.md`).
+    *   Load `FEATURE_DIR/plan.md` (or `specs/plan.md`).
+    *   Load `FEATURE_DIR/tasks.md` (or `specs/tasks.md`).
+    *   Ensure all files exist; if not, report which are missing (though tasks might not exist yet if only planning).
+
+2.  **Load Artifacts (Progressive Disclosure)**:
+    *   Load only necessary portions relevant to the feature.
+    *   Load `.specify/memory/constitution.md` for validation.
+
+3.  **Build Semantic Models**:
+    *   **Requirements inventory**: Functional + non-functional requirements.
+    *   **User story/action inventory**: User actions + acceptance criteria.
+    *   **Task coverage mapping**: Map task to requirement/story.
+    *   **Constitution rule set**: Principle names and MUST statements.
+
+4.  **Detection Passes**:
+    *   **Duplication**: Near-duplicate requirements.
+    *   **Ambiguity**: Vague adjectives ("fast", "robust") without metrics. Unresolved placeholders (TODO, ???).
+    *   **Underspecification**: Verbs missing objects/outcomes. User stories missing acceptance criteria.
+    *   **Constitution Alignment**: Conflict with MUST principles. Missing mandated sections.
+    *   **Coverage Gaps**: Requirements with zero tasks. Tasks with no mapped requirement.
+    *   **Inconsistency**: Terminology drift. Data entities in plan but absent in spec. Task order contradictions.
+
+5.  **Severity Assignment**:
+    *   **CRITICAL**: Violates constitution, missing core artifact, blocking requirement with zero coverage.
+    *   **HIGH**: Duplicate/conflicting requirement, ambiguous security/performance, untestable AC.
+    *   **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case.
+    *   **LOW**: Style/wording improvements.
+
+6.  **Produce Compact Analysis Report**:
+    *   Output a Markdown report with a findings table: | ID | Category | Severity | Location | Summary | Recommendation |
+    *   **Coverage Summary Table**: Requirement Key | Has Task? | Task IDs | Notes
+    *   **Metrics**: Total Requirements, Total Tasks, Coverage %, Ambiguity Count.
+
+7.  **Provide Next Actions**:
+    *   Recommend resolving CRITICAL issues before implementation.
+    *   Provide explicit suggestions (e.g., "Refine spec", "Adjust plan").
+
+8.  **Offer Remediation**:
+    *   Ask if the user wants concrete remediation edits for top N issues.
+
+## Operating Principles
+
+*   **Context Efficiency**: Focus on actionable findings.
+*   **NEVER modify files** automatically (read-only analysis).
+*   **NEVER hallucinate missing sections**.
+*   **Prioritize constitution violations**.

package/framework/.claude/skills/spec-clarification/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: spec-clarification
+description: Identify underspecified areas in the current feature spec by asking targeted clarification questions and encoding answers back into the spec.
+---
+
+# Specification Clarification
+
+## Overview
+
+Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+**Goal**: Identify 5 actionable clarification questions that materially impact implementation.
+
+## Execution Steps
+
+1.  **Initialize Context**:
+    *   Load the current spec file (`spec.md`).
+    *   Perform a structured ambiguity & coverage scan.
+    *   Identify missing or partial information in: Functional Scope, Domain & Data Model, Interaction & UX Flow, Non-Functional Quality, Integration & Dependencies, Edge Cases, Constraints, Terminology, Completion Signals, Misc/Placeholders.
+
+2.  **Generate Prioritized Questions**:
+    *   Create a queue of candidate clarification questions (max 5).
+    *   **Constraints**:
+        *   Answerable with Multiple Choice (2-5 options) OR Short Answer (<=5 words).
+        *   Materially impacts architecture, data modeling, task decomposition, test design, UX, or compliance.
+        *   Exclude style preferences or plan-level details unless blocking.
+        *   Favor impact * uncertainty heuristic.
+
+3.  **Sequential Questioning Loop (Interactive)**:
+    *   Present **ONE** question at a time.
+    *   **Multiple Choice**:
+        *   Analyze options based on best practices/risk/alignment.
+        *   Present **Recommended Option** with reasoning first.
+        *   Show table of options (A, B, C...).
+        *   Prompt user to reply with letter or "yes"/"recommended".
+    *   **Short Answer**:
+        *   Provide **Suggested Answer** based on context.
+        *   Prompt user to reply "yes"/"suggested" or own answer.
+    *   **After Answer**:
+        *   Validate answer.
+        *   Record in working memory.
+        *   Stop if: All critical ambiguities resolved, User says stop, or 5 questions reached.
+
+4.  **Integration (Incremental Update)**:
+    *   **After EACH accepted answer**:
+        *   Ensure a `## Clarifications` section exists (create if missing).
+        *   Append a bullet: `- Q: <question> → A: <final answer>`.
+        *   **Apply the clarification** to the appropriate section(s) in the spec:
+            *   Functional → Functional Requirements.
+            *   User Interaction → User Stories/Actors.
+            *   Data → Data Model.
+            *   Non-Functional → NFRs.
+            *   Edge Case → Edge Cases/Error Handling.
+            *   Terminology → Normalize terms.
+        *   **Save the spec file** immediately.
+
+5.  **Validation**:
+    *   Ensure exactly one bullet per answer.
+    *   Ensure no contradictory earlier statements remain.
+    *   Ensure Markdown structure is valid.
+
+6.  **Report Completion**:
+    *   Summarize questions asked & answered.
+    *   List sections touched.
+    *   Show coverage summary table (Resolved/Deferred/Clear/Outstanding).
+    *   Recommend next steps (e.g., Proceed to Planning).
+
+## Principles
+
+*   If no ambiguities, state "No critical ambiguities detected".
+*   Never exceed 5 questions.
+*   Avoid speculative tech stack questions unless blocking functional clarity.
+*   Respect explicit user stops.

package/framework/.claude/skills/sync-index/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: sync-index
+description: Keep project documentation (.agents/project-index.md and sub-skills) in sync with codebase changes.
+---
+
+# Documentation Sync
+
+## Overview
+
+Documentation drift is a major problem. Use this skill to ensure that the project index and agent guidance files are always up-to-date with the codebase.
+
+## Workflow
+
+1.  **Detect Changes**:
+    *   Ideally run after major feature implementation or refactoring.
+    *   Compare current file structure with `project-index.md`.
+
+2.  **Run Indexer**:
+    *   Execute the `project-index` skill again.
+    *   Verify that new modules/directories are captured.
+    *   Ensure deleted files are removed from documentation.
+
+3.  **Update Guidance**:
+    *   Check `agent-*.md` files in domain directories.
+    *   Update any obsolete instructions.
+    *   Add new patterns discovered during implementation.
+
+4.  **Verify Links**:
+    *   Ensure all links in `README.md` and `AGENTS.md` point to valid locations.
+
+## Output
+
+*   Updated `project-index.md`.
+*   Updated domain-specific agent guides.
+*   Confirmation of documentation sync.

package/framework/.claude/skills/test-generator/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: test-generator
+description: Generate comprehensive test suites ensuring requirements are met. Strategies for Unit, Integration, and E2E testing.
+---
+
+# Test Generation and Strategy
+
+## Overview
+
+Use this skill to systematically test features by generating high-quality test cases based on specifications and architectural design.
+
+## Workflow
+
+1.  **Analyze Requirements**:
+    *   Understand the "Why" and "What" from specs and user stories.
+    *   Identify key scenarios, edge cases, and failure modes.
+
+2.  **Define Test Strategy**:
+    *   **Unit Tests**: Test individual functions/methods in isolation. Mock external dependencies.
+    *   **Integration Tests**: Test interactions between modules (e.g., API + Database).
+    *   **End-to-End (E2E) Tests**: Test complete user flows from frontend to backend.
+    *   **Pyramid**: Ideally follow the test pyramid (Many Unit > Some Integration > Few E2E).
+
+3.  **Generate Test Code**:
+    *   Write test cases *before* implementation if possible (TDD).
+    *   Use established testing frameworks (Jest, PyTest, Mocha, Cypress, Playwright).
+    *   Ensure descriptive test names: `it("should return 404 when user not found")`.
+    *   Apply AAA pattern: Arrange, Act, Assert.
+
+## Quality Checklist
+
+*   **Coverage**: Do tests cover positive, negative, and edge cases?
+*   **Isolation**: Are unit tests independent and fast?
+*   **Reliability**: Are tests deterministic (no flaky tests)?
+*   **Mocking**: Are external services mocked appropriately?
+
+## Output
+
+*   Fully functional test files.
+*   Instructions on how to run tests.
+*   Suggestions for coverage improvements.