jmagly/scaffold-framework

Scaffold Framework

Create a complete framework package structure inside agentic/code/frameworks/.

Triggers

Alternate expressions and non-obvious activations (primary phrases are matched automatically from the skill description):

• "I need a new framework" → scaffold framework with guided design
• "create an AIWG framework" → prompt for name, scaffold
• "build a lifecycle framework for X" → derive name from X, scaffold with interactive mode
• "new framework package" → prompt for name and description

Trigger Patterns Reference

| Pattern | Example | Action | |---------|---------|--------| | Named scaffold | "scaffold framework legal-ops" | Scaffold directly | | Interactive | "scaffold framework --interactive" | Full guided design mode | | Described | "create a framework for content production pipelines" | Derive name=content-production, confirm | | Phased | "scaffold framework data-science --phases discovery,analysis,modeling,deployment" | Scaffold with custom phases |

Understanding Frameworks

Frameworks are major capability bundles that model complete operational lifecycles. They contain everything a team needs to manage a specific type of work end-to-end. Examples:

| Framework | Purpose | Scale | |-----------|---------|-------| | sdlc-complete | Software development lifecycle | ~58 agents, 100+ templates | | media-marketing-kit | Marketing operations | ~37 agents, campaign lifecycle | | forensics-complete | Digital forensics and IR | Investigation lifecycle | | research-complete | Research workflow automation | Research phases |

Frameworks differ from addons:

• Frameworks: Define a complete lifecycle with phases, transitions, and gate criteria
• Addons: Provide cross-cutting feature bundles installed alongside any framework

Framework creation is a significant undertaking. Study existing frameworks before building new ones. Start with core agents per phase, then expand.

Process

1. Parse Arguments

Extract from $ARGUMENTS:

• <name> — kebab-case framework name (required)
• --description "<text>" — short description (optional; prompted if absent)
• --phases "<p1,p2,...>" — comma-separated phase list (optional; defaults to inception,elaboration,construction,transition)
• --author "<name>" — author name (optional)
• --interactive — enable guided design questions

If <name> is missing, ask before proceeding.

2. Validate Name

• Must be kebab-case
• Must not conflict with existing frameworks:

ls agentic/code/frameworks/

3. Interactive Design (if --interactive)

This is the recommended path for first-time framework creation. Ask:

1. Lifecycle: What lifecycle does this framework manage? (software dev, marketing, legal, research)
2. Target audience: Who uses this framework? (engineering teams, marketing departments, legal firms)
3. Phase structure: What phases does this lifecycle include?
   • Default: inception → elaboration → construction → transition
   • Custom examples: discovery → analysis → synthesis → publication
4. Phase gates: What criteria must be met to transition between phases?
5. Agent categories: What specialist roles are needed per phase?
   • Analysis (analysts, researchers, planners)
   • Design (architects, designers, strategists)
   • Execution (developers, writers, implementers)
   • Quality (reviewers, testers, validators)
   • Coordination (managers, orchestrators, leads)
6. Template categories: What artifact types will this framework produce?
7. Core commands: What phase-execution and transition commands are needed?

4. Run Scaffolding

aiwg scaffold-framework <name> \
  --description "<description>" \
  --phases "<phase1,phase2,...>"

5. Customize Generated Files

manifest.json — Framework registry entry:

{
  "name": "<name>",
  "version": "1.0.0",
  "description": "<description>",
  "author": "<author>",
  "phases": ["<phase1>", "<phase2>"],
  "agents": [],
  "commands": [],
  "skills": [],
  "rules": [],
  "templates": {}
}

README.md — Framework overview: purpose, phases, agent catalog, quick start.

actors-and-templates.md — Maps roles to artifacts per phase. Critical for orchestration.

plan-act-<name>.md — Master plan-and-act document defining framework behavior.

6. Populate Phase Flows

Each phase gets a flow definition in flows/:

# <Phase> Phase Flow

## Objectives
[What this phase accomplishes]

## Entry Criteria
[What must be true to begin this phase]

## Activities
[What happens in this phase]

## Artifacts Produced
[Documents and deliverables]

## Exit Criteria / Gate
[What must be true to leave this phase]

## Agents
[Which agents are active in this phase]

7. Build Agent Catalog (Priority Order)

After scaffold, build agents in this order:

1. Phase 1: 2-3 core agents per phase (primary authors)
2. Phase 2: Reviewer agents for each phase
3. Phase 3: Orchestration agents for phase transitions

aiwg add-agent <role> --to <name> --template complex

8. Build Command Set (Priority Order)

1. Phase execution: flow-<phase> commands
2. Phase transitions: flow-<phase>-to-<next> commands
3. Utilities: project-status, gate-check, health-check

aiwg add-command flow-<phase> --to <name> --template orchestration

9. Deploy and Validate

# Deploy framework to active provider
aiwg use <name>

# Validate structure and metadata
aiwg validate-metadata

# Health check
aiwg doctor

Generated Structure

agentic/code/frameworks/<name>/
├── README.md                  # Framework documentation
├── manifest.json              # Framework configuration and registry
├── plan-act-<name>.md         # Master plan-and-act document
├── actors-and-templates.md    # Role-to-artifact mapping
├── agents/                    # Agent definitions (.md files)
├── skills/                    # Skill definitions
├── commands/                  # Slash command definitions
├── rules/                     # Framework-specific rules
├── templates/                 # Document templates (by category)
├── flows/                     # Phase flow definitions
│   ├── <phase1>.md
│   ├── <phase2>.md
│   └── ...
└── docs/                      # Framework documentation
    ├── orchestrator-architecture.md
    └── agent-catalog.md

Output Format

Framework Created: <name>
─────────────────────────
Location: agentic/code/frameworks/<name>/

Phases: <phase1> → <phase2> → ... → <phaseN>

Created:
  ✓ README.md
  ✓ manifest.json
  ✓ plan-act-<name>.md
  ✓ actors-and-templates.md
  ✓ agents/
  ✓ skills/
  ✓ commands/
  ✓ rules/
  ✓ templates/
  ✓ flows/<phase>.md  (for each phase)
  ✓ docs/

Next Steps:
  1. Define actors:   Edit actors-and-templates.md
  2. Add agents:      aiwg add-agent <role> --to <name>   (2-3 per phase)
  3. Add commands:    aiwg add-command flow-<phase> --to <name>
  4. Add templates:   aiwg add-template <artifact> --to <name> --category <phase>
  5. Deploy:          aiwg use <name>
  6. Validate:        aiwg validate-metadata

Reference frameworks:
  - sdlc-complete:        58 agents, ~100 templates (comprehensive)
  - media-marketing-kit:  37 agents, marketing-focused

Examples

Example 1: Standard lifecycle framework

User: "scaffold framework legal-ops"

Action:

aiwg scaffold-framework legal-ops \
  --description "Legal operations and case management lifecycle" \
  --phases "intake,investigation,analysis,drafting,review,close"

Result: agentic/code/frameworks/legal-ops/ created with six phase flow files and full directory structure.

Example 2: Interactive framework design

User: "scaffold framework --interactive"

Process: Guided questions establish the lifecycle type (e.g., content production), phases (ideation, research, writing, editing, publication), agent categories, and initial agent/command stubs.

Example 3: Research workflow framework

User: "create a new AIWG framework called data-science-ops"

Action:

aiwg scaffold-framework data-science-ops \
  --description "Data science project lifecycle management" \
  --phases "discovery,data-preparation,modeling,evaluation,deployment"

References

• @$AIWG_ROOT/agentic/code/addons/aiwg-utils/skills/devkit-create-framework/SKILL.md — Devkit equivalent (interactive design)
• @$AIWG_ROOT/src/cli/handlers/scaffolding.ts — CLI handler implementation
• @$AIWG_ROOT/docs/cli-reference.md — Full CLI reference
• @$AIWG_ROOT/docs/development/framework-creation-guide.md — Detailed framework authoring guide
• @$AIWG_ROOT/agentic/code/frameworks/sdlc-complete/ — Primary reference implementation
• @$AIWG_ROOT/agentic/code/frameworks/media-marketing-kit/ — Alternative reference implementation