ac-framework 1.6.0 → 1.8.0

package/framework/.kimi/workflows/opsx-sync.md

@@ -0,0 +1,131 @@
+---
+description: Sync delta specs from a change to main specs
+---
+
+Sync delta specs from a change to main specs.
+
+This is an **agent-driven** operation - you will read delta specs and directly edit main specs to apply the changes. This allows intelligent merging (e.g., adding a scenario without copying the entire requirement).
+
+**Input**: Optionally specify a change name after `/opsx:sync` (e.g., `/opsx:sync add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **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.
+
+   Show changes that have delta specs (under `specs/` directory).
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Find delta specs**
+
+   Look for delta spec files in `openspec/changes/<name>/specs/*/spec.md`.
+
+   Each delta spec file contains sections like:
+   - `## ADDED Requirements` - New requirements to add
+   - `## MODIFIED Requirements` - Changes to existing requirements
+   - `## REMOVED Requirements` - Requirements to remove
+   - `## RENAMED Requirements` - Requirements to rename (FROM:/TO: format)
+
+   If no delta specs found, inform user and stop.
+
+3. **For each delta spec, apply changes to main specs**
+
+   For each capability with a delta spec at `openspec/changes/<name>/specs/<capability>/spec.md`:
+
+   a. **Read the delta spec** to understand the intended changes
+
+   b. **Read the main spec** at `openspec/specs/<capability>/spec.md` (may not exist yet)
+
+   c. **Apply changes intelligently**:
+
+      **ADDED Requirements:**
+      - If requirement doesn't exist in main spec → add it
+      - If requirement already exists → update it to match (treat as implicit MODIFIED)
+
+      **MODIFIED Requirements:**
+      - Find the requirement in main spec
+      - Apply the changes - this can be:
+        - Adding new scenarios (don't need to copy existing ones)
+        - Modifying existing scenarios
+        - Changing the requirement description
+      - Preserve scenarios/content not mentioned in the delta
+
+      **REMOVED Requirements:**
+      - Remove the entire requirement block from main spec
+
+      **RENAMED Requirements:**
+      - Find the FROM requirement, rename to TO
+
+   d. **Create new main spec** if capability doesn't exist yet:
+      - Create `openspec/specs/<capability>/spec.md`
+      - Add Purpose section (can be brief, mark as TBD)
+      - Add Requirements section with the ADDED requirements
+
+4. **Show summary**
+
+   After applying all changes, summarize:
+   - Which capabilities were updated
+   - What changes were made (requirements added/modified/removed/renamed)
+
+**Delta Spec Format Reference**
+
+```markdown
+## ADDED Requirements
+
+### Requirement: New Feature
+The system SHALL do something new.
+
+#### Scenario: Basic case
+- **WHEN** user does X
+- **THEN** system does Y
+
+## MODIFIED Requirements
+
+### Requirement: Existing Feature
+#### Scenario: New scenario to add
+- **WHEN** user does A
+- **THEN** system does B
+
+## REMOVED Requirements
+
+### Requirement: Deprecated Feature
+
+## RENAMED Requirements
+
+- FROM: `### Requirement: Old Name`
+- TO: `### Requirement: New Name`
+```
+
+**Key Principle: Intelligent Merging**
+
+Unlike programmatic merging, you can apply **partial updates**:
+- To add a scenario, just include that scenario under MODIFIED - don't copy existing scenarios
+- The delta represents *intent*, not a wholesale replacement
+- Use your judgment to merge changes sensibly
+
+**Output On Success**
+
+```
+## Specs Synced: <change-name>
+
+Updated main specs:
+
+**<capability-1>**:
+- Added requirement: "New Feature"
+- Modified requirement: "Existing Feature" (added 1 scenario)
+
+**<capability-2>**:
+- Created new spec file
+- Added requirement: "Another Feature"
+
+Main specs are now updated. The change remains active - archive when implementation is complete.
+```
+
+**Guardrails**
+- Read both delta and main specs before making changes
+- Preserve existing content not mentioned in delta
+- If something is unclear, ask for clarification
+- Show what you're changing as you go
+- The operation should be idempotent - running twice should give same result

package/framework/.kimi/workflows/opsx-verify.md

@@ -0,0 +1,161 @@
+---
+description: Verify implementation matches change artifacts before archiving
+---
+
+Verify that an implementation matches the change artifacts (specs, tasks, design).
+
+**Input**: Optionally specify a change name after `/opsx:verify` (e.g., `/opsx:verify add-auth`). If omitted, check if it can be inferred from conversation context. If vague or ambiguous you MUST prompt for available changes.
+
+**Steps**
+
+1. **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.
+
+   Show changes that have implementation tasks (tasks artifact exists).
+   Include the schema used for each change if available.
+   Mark changes with incomplete tasks as "(In Progress)".
+
+   **IMPORTANT**: Do NOT guess or auto-select a change. Always let the user choose.
+
+2. **Check status to understand the schema**
+   ```bash
+   acfm spec status --change "<name>" --json
+   ```
+   Parse the JSON to understand:
+   - `schemaName`: The workflow being used (e.g., "spec-driven")
+   - Which artifacts exist for this change
+
+3. **Get the change directory and load artifacts**
+
+   ```bash
+   acfm spec instructions apply --change "<name>" --json
+   ```
+
+   This returns the change directory and context files. Read all available artifacts from `contextFiles`.
+
+4. **Initialize verification report structure**
+
+   Create a report structure with three dimensions:
+   - **Completeness**: Track tasks and spec coverage
+   - **Correctness**: Track requirement implementation and scenario coverage
+   - **Coherence**: Track design adherence and pattern consistency
+
+   Each dimension can have CRITICAL, WARNING, or SUGGESTION issues.
+
+5. **Verify Completeness**
+
+   **Task Completion**:
+   - If tasks.md exists in contextFiles, read it
+   - Parse checkboxes: `- [ ]` (incomplete) vs `- [x]` (complete)
+   - Count complete vs total tasks
+   - If incomplete tasks exist:
+     - Add CRITICAL issue for each incomplete task
+     - Recommendation: "Complete task: <description>" or "Mark as done if already implemented"
+
+   **Spec Coverage**:
+   - If delta specs exist in `openspec/changes/<name>/specs/`:
+     - Extract all requirements (marked with "### Requirement:")
+     - For each requirement:
+       - Search codebase for keywords related to the requirement
+       - Assess if implementation likely exists
+     - If requirements appear unimplemented:
+       - Add CRITICAL issue: "Requirement not found: <requirement name>"
+       - Recommendation: "Implement requirement X: <description>"
+
+6. **Verify Correctness**
+
+   **Requirement Implementation Mapping**:
+   - For each requirement from delta specs:
+     - Search codebase for implementation evidence
+     - If found, note file paths and line ranges
+     - Assess if implementation matches requirement intent
+     - If divergence detected:
+       - Add WARNING: "Implementation may diverge from spec: <details>"
+       - Recommendation: "Review <file>:<lines> against requirement X"
+
+   **Scenario Coverage**:
+   - For each scenario in delta specs (marked with "#### Scenario:"):
+     - Check if conditions are handled in code
+     - Check if tests exist covering the scenario
+     - If scenario appears uncovered:
+       - Add WARNING: "Scenario not covered: <scenario name>"
+       - Recommendation: "Add test or implementation for scenario: <description>"
+
+7. **Verify Coherence**
+
+   **Design Adherence**:
+   - If design.md exists in contextFiles:
+     - Extract key decisions (look for sections like "Decision:", "Approach:", "Architecture:")
+     - Verify implementation follows those decisions
+     - If contradiction detected:
+       - Add WARNING: "Design decision not followed: <decision>"
+       - Recommendation: "Update implementation or revise design.md to match reality"
+   - If no design.md: Skip design adherence check, note "No design.md to verify against"
+
+   **Code Pattern Consistency**:
+   - Review new code for consistency with project patterns
+   - Check file naming, directory structure, coding style
+   - If significant deviations found:
+     - Add SUGGESTION: "Code pattern deviation: <details>"
+     - Recommendation: "Consider following project pattern: <example>"
+
+8. **Generate Verification Report**
+
+   **Summary Scorecard**:
+   ```
+   ## Verification Report: <change-name>
+
+   ### Summary
+   | Dimension    | Status           |
+   |--------------|------------------|
+   | Completeness | X/Y tasks, N reqs|
+   | Correctness  | M/N reqs covered |
+   | Coherence    | Followed/Issues  |
+   ```
+
+   **Issues by Priority**:
+
+   1. **CRITICAL** (Must fix before archive):
+      - Incomplete tasks
+      - Missing requirement implementations
+      - Each with specific, actionable recommendation
+
+   2. **WARNING** (Should fix):
+      - Spec/design divergences
+      - Missing scenario coverage
+      - Each with specific recommendation
+
+   3. **SUGGESTION** (Nice to fix):
+      - Pattern inconsistencies
+      - Minor improvements
+      - Each with specific recommendation
+
+   **Final Assessment**:
+   - If CRITICAL issues: "X critical issue(s) found. Fix before archiving."
+   - If only warnings: "No critical issues. Y warning(s) to consider. Ready for archive (with noted improvements)."
+   - If all clear: "All checks passed. Ready for archive."
+
+**Verification Heuristics**
+
+- **Completeness**: Focus on objective checklist items (checkboxes, requirements list)
+- **Correctness**: Use keyword search, file path analysis, reasonable inference - don't require perfect certainty
+- **Coherence**: Look for glaring inconsistencies, don't nitpick style
+- **False Positives**: When uncertain, prefer SUGGESTION over WARNING, WARNING over CRITICAL
+- **Actionability**: Every issue must have a specific recommendation with file/line references where applicable
+
+**Graceful Degradation**
+
+- If only tasks.md exists: verify task completion only, skip spec/design checks
+- If tasks + specs exist: verify completeness and correctness, skip design
+- If full artifacts: verify all three dimensions
+- Always note which checks were skipped and why
+
+**Output Format**
+
+Use clear markdown with:
+- Table for summary scorecard
+- Grouped lists for issues (CRITICAL/WARNING/SUGGESTION)
+- Code references in format: `file.ts:123`
+- Specific, actionable recommendations
+- No vague suggestions like "consider reviewing"

package/framework/.opencode/command/ac-lite.md

@@ -0,0 +1,192 @@
+**Fundamental Principle**: *"Quality with focused context. Load only what is necessary, when it is necessary."*
+
+---
+
+## Purpose
+
+`ac-lite` keeps the same spec-driven quality bar as `ac.md`, but reduces token usage by:
+
+1. Loading only the core workflow skills by default.
+2. Activating extra skills only when objective risk gates require them.
+3. Enforcing mandatory quality checkpoints before implementation and archive.
+
+---
+
+## Default Skill Set (Always Load)
+
+These are the only mandatory skills for every change:
+
+1. `acfm-spec-workflow`
+2. `openspec-new-change` OR `openspec-ff-change`
+3. `openspec-continue-change`
+4. `openspec-apply-change`
+5. `openspec-verify-change`
+6. `openspec-archive-change`
+
+---
+
+## Conditional Skills (Load Only If Gate Triggers)
+
+### Security Gate
+
+Load `secure-coding-cybersecurity` if the change touches any of:
+
+- Auth/session/permissions
+- User input handling or validation
+- SQL/ORM queries or dynamic filters
+- File paths/uploads
+- Secrets/tokens/credentials
+- Shell/command execution
+
+### Testing Gate
+
+Load `test-generator` if:
+
+- There are no tests for the changed behavior, or
+- Existing tests do not cover acceptance criteria, or
+- Regression risk is medium/high.
+
+### Consistency Gate
+
+Load `spec-analysis` and `requirement-checklist` if:
+
+- Requirements are ambiguous, or
+- Change spans multiple modules, or
+- Change modifies core domain behavior.
+
+### API Gate
+
+Load `api-design-principles` if API contracts/endpoints/schemas are added or modified.
+
+### UI Gate
+
+Load `interface-design` if dashboard/app UI behavior is introduced or changed.
+
+### Performance Gate
+
+Load `performance-optimizer` if:
+
+- The change affects hot paths, or
+- Latency/throughput targets exist, or
+- A performance regression is detected/suspected.
+
+### Context Scale Gate
+
+Load `project-index` and/or `context-synthesizer` if:
+
+- Codebase is large and discovery cost is high, or
+- Session is long and context drift appears.
+
+### Debug Gate
+
+Load `systematic-debugging` when blocked by non-trivial bugs or unstable behavior.
+
+---
+
+## Mandatory Quality Gates
+
+These gates are non-optional in `ac-lite`.
+
+### Gate A: Ready to Implement
+
+Before `openspec-apply-change`, all must be true:
+
+- Change exists and status is valid (`acfm spec status --change <name> --json`)
+- `tasks.md` exists with actionable checkboxes
+- Acceptance criteria are clear in artifacts
+- Required conditional skills (if triggered) were executed
+
+If any item fails: stop, resolve, then continue.
+
+### Gate B: Ready to Archive
+
+Before `openspec-archive-change`, all must be true:
+
+- `openspec-verify-change` completed
+- No CRITICAL findings remain
+- Relevant tests pass for changed behavior
+- Tasks are complete or explicitly accepted by user with warning
+
+If any item fails: stop, fix, re-verify.
+
+---
+
+## Lite Workflows
+
+### New Change (Default Path)
+
+1. Run `acfm-spec-workflow` checks (`acfm spec status --json`, init if needed).
+2. Create change with `openspec-new-change` (or `openspec-ff-change` if user requests speed).
+3. Build artifacts with `openspec-continue-change` until apply-ready.
+4. Evaluate conditional gates and load only triggered skills.
+5. Pass Gate A.
+6. Implement with `openspec-apply-change`.
+7. Verify with `openspec-verify-change`.
+8. Pass Gate B.
+9. Archive with `openspec-archive-change`.
+
+### Existing Change (Default Path)
+
+1. Confirm initialization and active changes.
+2. Select target change.
+3. Refresh artifact status.
+4. Evaluate conditional gates (only load what triggers).
+5. Pass Gate A.
+6. Implement.
+7. Verify.
+8. Pass Gate B.
+9. Archive.
+
+---
+
+## Operational Rules
+
+1. Do not load broad quality/documentation skills by default.
+2. Do not run optional skills "just in case".
+3. If risk increases during implementation, activate the matching conditional skill immediately.
+4. Prefer deterministic CLI checks over narrative assumptions.
+5. Keep outputs concise but auditable (show which gates passed/failed and why).
+
+---
+
+## Suggested Minimal Execution Template
+
+Use this structure in each run:
+
+1. **Change Context**
+   - Change name
+   - Current artifact progress
+
+2. **Triggered Gates**
+   - Security: pass/fail + reason
+   - Testing: pass/fail + reason
+   - Consistency/API/UI/Performance/Context/Debug: pass/fail + reason
+
+3. **Skills Loaded**
+   - Core: always list
+   - Conditional: list only triggered ones
+
+4. **Gate A Status**
+   - Ready to implement: yes/no
+
+5. **Implementation + Verify**
+   - What was implemented
+   - Verify findings summary
+
+6. **Gate B Status**
+   - Ready to archive: yes/no
+
+7. **Archive Result**
+   - Archive path and timestamp
+
+---
+
+## Token Strategy Summary
+
+`ac-lite` reduces cost by replacing "load everything first" with:
+
+- Mandatory core workflow only
+- Risk-gated skill expansion
+- Hard quality checkpoints at implementation and archive boundaries
+
+This preserves software quality while avoiding unnecessary instruction/context overhead.