fable-workflow

Files (4)

• SKILL.md
• openai.yaml · agents/
• test_workflow_state.py · scripts/
• workflow_state.py · scripts/

SKILL.md (first lines)

# Fable Workflow

Run the engagement from durable state and verified artifacts. This is the
operational entry point for the plugin; specialist Fable skills provide the
rules used at each transition.

## Select a Mode

- **Start**: turn a large objective into independent, gated slices.
- **Dispatch**: send one ready slice to a worker and record the assignment.
- **Intake and review**: reconcile returned work, prove it, and decide the next
  transition.
- **Recover**: rebuild truth after a task, agent, or worktree interruption.
- **Close**: verify terminal evidence and report residuals.

Do not invent workflow state. Read the state file and current repository before
choosing a mode.

## State Tool

Use `scripts/workflow_state.py` from this skill directory. Store state in the
target repository at `.fable/workflow.json` unless the repository names another
durable task tracker.

```powershell
python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json summary
python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json check
```

The tool records coordination state; it does not create worktrees, launch
agents, push branches, open pull requests, or merge changes.

## Start

1. Inspect the repository, current branch, instructions, tests, open work, and
   available agent capacity.
2. Apply `fable-orchestrator` to decide whether the objective truly benefits
   from bounded parallelism. Use a local single-slice workflow when it does not.
3. Split the objective into independent slices. Each slice must name scope,
   invariant, non-scope, and a fail-under-broken gate.
4. Initialize state and add the slices:

   ```powershell
   python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json init --objective "<objective>" --base-branch "<branch>"
   python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json add --id "<slice-id>" --summary "<summary>" --scope "<paths>" --invariant "<property>" --non-scope "<excluded work>" --gate "<proof command or artifact>"
   ```

5. Run `check`. Do not dispatch a slice whose contract is incomplete.

## Dispatch

1. Select a `queued`, dependency-ready slice with a non-overlapping write set.
2. Apply `agent-dispatch-packet`. Add `phase-aware-engineering-ladder` when
   exposure changes required rigor; apply `investigate-before-fix` for delicate
   diagnoses.
3. Launch a worker only when an agent mechanism is actually available and the
   conductor can do useful work concurrently. Otherwise execute the slice
   locally; never fabricate an agent assignment.
4. After a real launch or local ownership decision, record it:

   ```powershell
   python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json assign --id "<slice-id>" --worker "<worker-or-local>" --branch "<branch>" --worktree "<path>"
   ```

5. The worker applies `one-slice-worker-cycle` and returns the real artifact,
   commands run, evidence, residuals, and result state. Assignment does not
   authorize commit, push, pull-request, or merge actions beyond the user's
   request.

## Intake and Review

1. Match the completion event to the state item and open the actual branch,
   worktree, diff, pull request, CI run, or report.
2. Record evidence with its current outcome and head identifier when relevant:

   ```powershell
   python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json evidence --id "<slice-id>" --kind command --outcome pass --value "<command and result>" --head "<sha>"
   ```

3. Move implemented work to `review`.
4. Apply the review chain:
   - `task-relative-test-gate` checks the ruler;
   - `two-critic-review-loop` separates proof and change review;
   - `review-verifier` checks load-bearing critic claims at current HEAD;
   - `agent-pr-validator` makes the final claim-to-diff and CI decision.
5. Record critic, CI, diff, and runtime evidence separately. Mark `done` only
   after at least one current passing evidence record exists. Use `refuted` when
   the original diagnosis was disproven, and `held` only with explicit residual
   evidence.
6. Serialize merges. After a merge, refresh the next slice against the updated
   base before trusting its earlier evidence.

## Recover

1. Run `summary` and `check`.
2. Reconcile every non-terminal item against the actual repository artifacts.
3. Correct stale assignments with `set-status`; do not assume a missing worker
   failed or succeeded.
4. Apply `orphaned-wip-adopter` only after confirming a worktree is inactive.
5. Apply `long-run-continuity` and persist the exact next gate before leaving
   recovery.

## Close

1. Run the repository's real gates and record their evidence.
2. Run `check`, then:

   ```powershell
   python <skill-dir>/scripts/workflow_state.py --state <repo>/.fable/workflow.json close
   ```

3. `close` rejects queued, in-progress, review, or blocked slices. It accepts
   only proven `done`, evidenced `refuted`, or explicitly evidenced `held`
   outcomes.
4. Apply `periodic-retrospect` once to capture repeated failures or dropped
   residuals. Do not claim completion when the state tool or repository gate is
   red.

## Output

From kas1987/fable-agent-orchestration, Apache-2.0.

More from kas1987/fable-agent-orchestration