Add optional machine-readable workflow companion specs for complex gated skills

# Add optional machine-readable workflow companion specs for complex gated skills

## Summary

Some skills in this repo are simple enough to live entirely in `SKILL.md`.

Others are complex gated workflows with phases, guardrails, verification requirements, and anti-rationalization checks.

Examples:

```text
spec-driven-development
test-driven-development
interview-me collaborative mode
planning-and-task-breakdown
shipping-and-launch
```

For these complex skills, it may be useful to support an optional machine-readable companion file that mirrors the workflow in a structured format.

This would not replace `SKILL.md`.

`SKILL.md` should remain the human/model-facing source.

The companion file would only make the workflow easier to route, validate, test, and audit.

## Problem

The skills in this repo already encode real engineering workflows, not just advice.

Many of them include:

```text
ordered phases
gates
exit criteria
anti-rationalization rules
evidence requirements
red flags
verification checks
handoffs to other skills
```

This is great for agents, but hard for tooling to inspect.

For example, a tool cannot easily answer:

```text
Which skills require human approval?
Which skills have verification gates?
Which skills can invoke other skills?
Which skills are safe to auto-load?
Which skills are user-invoked only?
Which skills require evidence before completion?
Which skills include anti-rationalization checks?
```

Today, much of that information exists in prose.

## Proposal

Allow complex skills to optionally include a machine-readable workflow companion.

Possible layout:

```text
skills/spec-driven-development/
├── SKILL.md
└── workflow.aisop.json
```

or:

```text
skills/spec-driven-development/
├── SKILL.md
└── aisop/
└── spec-driven-development.aisop.json
```

The companion file could describe:

```text
workflow graph
ordered phases
required gates
verification steps
evidence requirements
handoff points
related skills
hard constraints
```

This file would be optional.

Skills without it continue to work exactly as they do today.

## Example: spec-driven-development

`spec-driven-development` already has a clear gated workflow:

```text
SPECIFY
-> human review
-> PLAN
-> human review
-> TASKS
-> human review
-> IMPLEMENT
```

A companion file could express that shape as a workflow graph.

For example, using strict AISOP V1.0.0:

```json
[
{
"role": "system",
"content": {
"protocol": "AISOP V1.0.0",
"axiom_0": "Human_Sovereignty_and_Wellbeing",
"id": "spec_driven_development_workflow",
"name": "Spec Driven Development Workflow",
"version": "1.0.0",
"summary": "Machine-readable companion workflow for spec-driven development phases and gates.",
"flow_format": "mermaid",
"loading_mode": "node",
"tools": ["filesystem"],
"params": {
"feature_goal": "string"
},
"system_prompt": "{system_prompt}"
}
},
{
"role": "user",
"content": {
"instruction": "RUN aisop.main",
"user_input": "{user_input}",
"aisop": {
"main": "graph TD\n specify[Write specification] --> review_spec[Human review spec]\n review_spec --> plan[Write implementation plan]\n plan --> review_plan[Human review plan]\n review_plan --> tasks[Break into tasks]\n tasks --> review_tasks[Human review tasks]\n review_tasks --> implement[Implement incrementally]\n implement --> verify[Verify evidence]\n verify --> end_node((End))"
},
"functions": {
"specify": {
"step1": "Write a structured specification before implementation.",
"step2": "Include objective, commands, project structure, code style, testing strategy, and boundaries.",
"output_mapping": "specification",
"constraints": [
"Do not start implementation before the specification exists.",
"Do not omit testing strategy or boundaries."
]
},
"review_spec": {
"step1": "Ask the user to review and approve the specification.",
"step2": "sys.assert('specification approved by user', 'Specification must be reviewed before planning')",
"output_mapping": "spec_review_status"
},
"plan": {
"step1": "Write an implementation plan based on the approved specification.",
"output_mapping": "implementation_plan",
"constraints": [
"The plan must reference the approved specification.",
"Do not introduce scope not present in the specification without surfacing it."
]
},
"review_plan": {
"step1": "Ask the user to review and approve the implementation plan.",
"step2": "sys.assert('implementation plan approved by user', 'Implementation plan must be reviewed before task breakdown')",
"output_mapping": "plan_review_status"
},
"tasks": {
"step1": "Break the implementation plan into tasks with acceptance criteria and verification steps.",
"output_mapping": "task_list",
"constraints": [
"Each task must have acceptance criteria.",
"Each task must have a verification method."
]
},
"review_tasks": {
"step1": "Ask the user to review and approve the task list.",
"step2": "sys.assert('task list approved by user', 'Task list must be reviewed before implementation')",
"output_mapping": "task_review_status"
},
"implement": {
"step1": "Implement tasks incrementally.",
"step2": "Use related skills such as incremental-implementation and test-driven-development when appropriate.",
"output_mapping": "implementation_result",
"constraints": [
"Do not batch unrelated tasks.",
"Do not skip tests for behavior changes."
]
},
"verify": {
"step1": "Verify that implementation evidence satisfies the specification and task acceptance criteria.",
"step2": "sys.assert('all acceptance criteria verified', 'Implementation is incomplete without verification evidence')",
"output_mapping": "verification_result"
},
"end_node": {
"step1": "Return implementation_result and verification_result."
}
}
}
}
]
```

## Why this helps

A companion workflow file could support:

```text
1. router/index generation
2. skill dependency discovery
3. verification gate detection
4. human-review gate detection
5. anti-rationalization checks
6. traceability from process to evidence
7. tests that verify workflow structure
```

It could also help the proposed `skill-router` idea.

Instead of loading every `SKILL.md`, a router could inspect compact metadata from companion files or a generated index.

## Non-goals

This should not:

```text
1. replace SKILL.md;
2. require every skill to have a companion file;
3. introduce a heavy framework;
4. require one specific protocol;
5. make skill authoring harder for simple skills.
```

The companion should be optional and only useful for complex gated workflows.

## Possible first step

Start with one skill:

```text
spec-driven-development
```

It already has clear phases and review gates, so it is a good candidate.

The first PR could add only:

```text
skills/spec-driven-development/aisop/spec-driven-development.aisop.json
```

and a short docs note:

```text
Companion workflow files are optional. SKILL.md remains the source for human/model-facing instructions.
```

This would let the repo experiment with machine-readable workflow structure without changing how existing skills are used.