ac-framework 1.6.0 → 1.8.0

package/framework/.agent/skills/openspec-ff-change/SKILL.md

@@ -15,7 +15,23 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
 **Steps**
 
-1. **If no clear input provided, ask what they want to build**
+1. **Verify project initialization**
+
+   Check if the project is initialized:
+   ```bash
+   acfm spec status --json
+   ```
+   
+   **If not initialized** (`"initialized": false`):
+   ```bash
+   acfm spec init
+   ```
+   
+   **If initialized** (`"initialized": true`):
+   - Note the `dirName` field (either `.acfm` or `openspec`)
+   - Continue with the workflow
+
+2. **If no clear input provided, ask what they want to build**
 
    Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
    > "What change do you want to work on? Describe what you want to build or fix."
@@ -24,13 +40,13 @@ Fast-forward through artifact creation - generate everything needed to start imp
 
    **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
 
-2. **Create the change directory**
+3. **Create the change directory**
    ```bash
    acfm spec new "<name>"
    ```
    This creates a scaffolded change at `openspec/changes/<name>/`.
 
-3. **Get the artifact build order**
+4. **Get the artifact build order**
    ```bash
    acfm spec status --change "<name>" --json
    ```
@@ -38,7 +54,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
    - `applyRequires`: array of artifact IDs needed before implementation (e.g., `["tasks"]`)
    - `artifacts`: list of all artifacts with their status and dependencies
 
-4. **Create artifacts in sequence until apply-ready**
+5. **Create artifacts in sequence until apply-ready**
 
    Use the **TodoWrite tool** to track progress through the artifacts.
 
@@ -70,7 +86,7 @@ Fast-forward through artifact creation - generate everything needed to start imp
       - Use **AskUserQuestion tool** to clarify
       - Then continue with creation
 
-5. **Show final status**
+6. **Show final status**
    ```bash
    acfm spec status --change "<name>"
    ```

package/framework/.agent/skills/openspec-new-change/SKILL.md

@@ -15,7 +15,23 @@ Start a new change using the experimental artifact-driven approach.
 
 **Steps**
 
-1. **If no clear input provided, ask what they want to build**
+1. **Verify project initialization**
+
+   Check if the project is initialized:
+   ```bash
+   acfm spec status --json
+   ```
+   
+   **If not initialized** (`"initialized": false`):
+   ```bash
+   acfm spec init
+   ```
+   
+   **If initialized** (`"initialized": true`):
+   - Note the `dirName` field (either `.acfm` or `openspec`)
+   - Continue with the workflow
+
+2. **If no clear input provided, ask what they want to build**
 
    Use the **AskUserQuestion tool** (open-ended, no preset options) to ask:
    > "What change do you want to work on? Describe what you want to build or fix."
@@ -24,7 +40,7 @@ Start a new change using the experimental artifact-driven approach.
 
    **IMPORTANT**: Do NOT proceed without understanding what the user wants to build.
 
-2. **Determine the workflow schema**
+3. **Determine the workflow schema**
 
    Use the default schema (omit `--schema`) unless the user explicitly requests a different workflow.
 
@@ -34,20 +50,20 @@ Start a new change using the experimental artifact-driven approach.
 
    **Otherwise**: Omit `--schema` to use the default.
 
-3. **Create the change directory**
+4. **Create the change directory**
    ```bash
    acfm spec new "<name>"
    ```
    Add `--schema <name>` only if the user requested a specific workflow.
-   This creates a scaffolded change at `openspec/changes/<name>/` with the selected schema.
+   This creates a scaffolded change at `{specDir}/changes/<name>/` (where {specDir} is either `.acfm` or `openspec` as detected by CLI) with the selected schema.
 
-4. **Show the artifact status**
+5. **Show the artifact status**
    ```bash
    acfm spec status --change "<name>"
    ```
    This shows which artifacts need to be created and which are ready (dependencies satisfied).
 
-5. **Get instructions for the first artifact**
+6. **Get instructions for the first artifact**
    The first artifact depends on the schema (e.g., `proposal` for spec-driven).
    Check the status output to find the first artifact with status "ready".
    ```bash
@@ -55,7 +71,7 @@ Start a new change using the experimental artifact-driven approach.
    ```
    This outputs the template and context for creating the first artifact.
 
-6. **STOP and wait for user direction**
+7. **STOP and wait for user direction**
 
 **Output**
 

package/framework/.agent/skills/openspec-sync-specs/SKILL.md

@@ -17,7 +17,23 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Verify project initialization**
+
+   Check if the project is initialized:
+   ```bash
+   acfm spec status --json
+   ```
+   
+   **If not initialized** (`"initialized": false`):
+   ```bash
+   acfm spec init
+   ```
+   
+   **If initialized** (`"initialized": true`):
+   - Note the `dirName` field (either `.acfm` or `openspec`)
+   - Continue with the workflow
+
+2. **If no change name provided, prompt for selection**
 
    Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
@@ -25,7 +41,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
    **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
 
-2. **Find delta specs**
+3. **Find delta specs**
 
    Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
 
@@ -37,7 +53,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
 
    If no delta specs found, inform user and stop.
 
-3. **For each delta spec, apply changes to main specs**
+4. **For each delta spec, apply changes to main specs**
 
    For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
 
@@ -70,7 +86,7 @@ This is an **agent-driven** operation - you will read delta specs and directly e
       - Add Purpose section (can be brief, mark as TBD)
       - Add Requirements section with the ADDED requirements
 
-4. **Show summary**
+5. **Show summary**
 
    After applying all changes, summarize:
    - Which capabilities were updated

package/framework/.agent/skills/openspec-verify-change/SKILL.md

@@ -15,7 +15,23 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
 **Steps**
 
-1. **If no change name provided, prompt for selection**
+1. **Verify project initialization**
+
+   Check if the project is initialized:
+   ```bash
+   acfm spec status --json
+   ```
+   
+   **If not initialized** (`"initialized": false`):
+   ```bash
+   acfm spec init
+   ```
+   
+   **If initialized** (`"initialized": true`):
+   - Note the `dirName` field (either `.acfm` or `openspec`)
+   - Continue with the workflow
+
+2. **If no change name provided, prompt for selection**
 
    Run `acfm spec list --json` to get available changes. Use the **AskUserQuestion tool** to let the user select.
 
@@ -25,7 +41,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
    **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
 
-2. **Check status to understand the schema**
+3. **Check status to understand the schema**
    ```bash
    acfm spec status --change "<name>" --json
    ```
@@ -33,7 +49,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
    - `schemaName`: The workflow being used (e.g., "spec-driven")
    - Which artifacts exist for this change
 
-3. **Get the change directory and load artifacts**
+4. **Get the change directory and load artifacts**
 
    ```bash
    acfm spec instructions apply --change "<name>" --json
@@ -41,7 +57,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
    This returns the change directory and context files. Read all available artifacts from `contextFiles`.
 
-4. **Initialize verification report structure**
+5. **Initialize verification report structure**
 
    Create a report structure with three dimensions:
    - **Completeness**: Track tasks and spec coverage
@@ -50,7 +66,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
 
    Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
 
-5. **Verify Completeness**
+6. **Verify Completeness**
 
    **Task Completion**:
    - If tasks.md exists in contextFiles, read it
@@ -70,7 +86,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
        - Add CRITICAL issue: "Requirement not found: <requirement name>"
        - Recommendation: "Implement requirement X: <description>"
 
-6. **Verify Correctness**
+7. **Verify Correctness**
 
    **Requirement Implementation Mapping**:
    - For each requirement from delta specs:
@@ -89,7 +105,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
        - Add WARNING: "Scenario not covered: <scenario name>"
        - Recommendation: "Add test or implementation for scenario: <description>"
 
-7. **Verify Coherence**
+8. **Verify Coherence**
 
    **Design Adherence**:
    - If design.md exists in contextFiles:
@@ -107,7 +123,7 @@ Verify that an implementation matches the change artifacts (specs, tasks, design
      - Add SUGGESTION: "Code pattern deviation: <details>"
      - Recommendation: "Consider following project pattern: <example>"
 
-8. **Generate Verification Report**
+9. **Generate Verification Report**
 
    **Summary Scorecard**:
    ```

package/framework/.agent/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