AC Framework Spec-Driven Workflow

Guide for initializing and managing spec-driven development workflows using the AC Framework CLI (acfm).

When to use this skill

Use this skill when:

• Starting a new project and need to initialize the spec workflow
• Working on an existing project and need to check if specs are initialized
• Creating a new change/feature using the spec-driven workflow
• Unsure whether to use .acfm/ or openspec/ directories
• Need to understand CLI commands for spec management
• Migrating from legacy openspec/ to new .acfm/ structure

Quick start

bash
1# Check if project is initialized
2acfm spec status --json
3
4# Initialize new project (creates .acfm/)
5acfm spec init
6
7# Create a new change
8acfm spec new my-feature --json
9
10# Get instructions for next artifact
11acfm spec instructions proposal --change my-feature --json

Directory Structure

NEW (Default): .acfm/ directory

project-root/
├── .acfm/                    # NEW: Default spec directory
│   ├── config.yaml           # Project configuration
│   ├── specs/                # Shared specs
│   └── changes/              # Active changes
│       ├── archive/          # Archived changes
│       └── my-feature/       # Individual change
│           ├── .openspec.yaml
│           ├── proposal.md
│           ├── design.md
│           ├── tasks.md
│           └── specs/

LEGACY: openspec/ directory

project-root/
├── openspec/                 # LEGACY: Still fully supported
│   ├── config.yaml
│   ├── specs/
│   └── changes/

Priority: CLI automatically uses .acfm/ if it exists, otherwise falls back to openspec/.

Instructions

Step 1: Check initialization status

Always start by checking if the project is initialized:

bash
1acfm spec status --json

If not initialized ("initialized": false):

• Proceed to Step 2 to initialize

If initialized ("initialized": true):

• Note the dirName field (either .acfm or openspec)
• Proceed to Step 3 to create changes

Step 2: Initialize the project

For new projects:

bash
1acfm spec init

This creates:

• .acfm/config.yaml - Project configuration
• .acmf/specs/ - Shared specifications
• .acfm/changes/ - Active changes directory

Legacy support: If the project already has openspec/, it will be detected automatically. No need to migrate unless desired.

Step 3: Create a change

bash
1acfm spec new <change-name> --json

Example:

bash
1acfm spec new user-authentication --json

Output:

json
1{
2  "changeDir": "/project/.acfm/changes/user-authentication",
3  "schemaName": "spec-driven",
4  "artifacts": ["proposal", "specs", "design", "tasks"]
5}

Step 4: Get instructions for artifacts

Each artifact has specific instructions:

bash
1# Get instructions for proposal
2acfm spec instructions proposal --change <name> --json
3
4# Get instructions for design
5acfm spec instructions design --change <name> --json
6
7# Get instructions for tasks
8acfm spec instructions tasks --change <name> --json
9
10# Get apply instructions (when ready to implement)
11acfm spec instructions apply --change <name> --json

Step 5: Check status

Monitor progress:

bash
1# Status of specific change
2acfm spec status --change <name> --json
3
4# List all changes
5acfm spec list --json

Step 6: Archive completed changes

bash
1acfm spec archive <change-name>

CLI Command Reference

Initialization

• acfm spec init [--json] - Initialize spec directory
• acfm spec status [--json] - Check initialization status

Change Management

• acfm spec new <name> [--json] - Create new change
• acfm spec list [--json] - List all changes
• acfm spec status --change <name> [--json] - Check change status
• acfm spec archive <name> [--json] - Archive completed change

Instructions

• acfm spec instructions <artifact> --change <name> [--json] - Get artifact instructions
• acfm spec schemas [--json] - List available schemas
• acfm spec validate <name> [--json] - Validate change structure

Common scenarios

Scenario: New project setup

bash
1# 1. Check status
2acfm spec status --json
3
4# 2. Initialize
5acfm spec init
6
7# 3. Create first change
8acfm spec new initial-setup --json
9
10# 4. Get proposal instructions
11acfm spec instructions proposal --change initial-setup --json

Scenario: Legacy project (openspec/)

bash
1# CLI automatically detects openspec/ directory
2acfm spec status --json
3# Output: { "initialized": true, "dirName": "openspec", ... }
4
5# Create change in openspec/
6acfm spec new legacy-feature --json
7# Creates: openspec/changes/legacy-feature/

Scenario: Mixed directories

If both .acfm/ and openspec/ exist:

• CLI uses .acfm/ (higher priority)
• Changes are created in .acfm/changes/

To use openspec/ temporarily:

bash
1mv .acfm/ .acfm-backup/
2# Now CLI will use openspec/

Best practices

1. Always use CLI commands - Don't manually create directories
2. Use --json flag for programmatic parsing
3. Check initialization first - Before creating changes
4. Let CLI handle paths - Don't hardcode .acfm/ or openspec/
5. Archive completed changes - Keeps active list clean

Troubleshooting

"Spec system not initialized"

bash
1# Solution
2acfm spec init

Changes not appearing

bash
1# Check which directory is being used
2acfm spec status --json
3# Look at "dirName" field
4
5# List both directories
6ls -la .acfm/changes/ 2>/dev/null || echo "No .acfm/"
7ls -la openspec/changes/ 2>/dev/null || echo "No openspec/"

Wrong directory detected

bash
1# Force use of openspec/ by renaming .acfm/
2mv .acfm/ .acfm-backup/
3
4# Or force use of .acfm/ by renaming openspec/
5mv openspec/ openspec-backup/

Requirements

• AC Framework CLI (acfm) must be installed
• Node.js >= 18.0.0

Compatibility

• ✅ Works with both .acfm/ (new) and openspec/ (legacy)
• ✅ All existing OpenSpec skills continue to work
• ✅ No migration required for legacy projects
• ✅ Optional migration path available

See also

• Use openspec-new-change skill after initialization to create structured changes
• Use openspec-continue-change to work on existing changes
• Use openspec-apply-change to implement tasks