mirror of
https://github.com/azaion/loader.git
synced 2026-04-22 22:06:33 +00:00
Oleksandr Bezdieniezhnykh
93 lines
4.5 KiB
Markdown
93 lines
4.5 KiB
Markdown
# Autopilot State Management
|
|
|
|
## State File: `_docs/_autopilot_state.md`
|
|
|
|
The autopilot persists its position to `_docs/_autopilot_state.md`. This is a lightweight pointer — only the current step. All history lives in `_docs/` artifacts and git log. Folder scanning is the fallback when the state file doesn't exist.
|
|
|
|
### Template
|
|
|
|
```markdown
|
|
# Autopilot State
|
|
|
|
## Current Step
|
|
flow: [greenfield | existing-code]
|
|
step: [1-10 for greenfield, 1-13 for existing-code, or "done"]
|
|
name: [step name from the active flow's Step Reference Table]
|
|
status: [not_started / in_progress / completed / skipped / failed]
|
|
sub_step: [0, or sub-skill internal step number + name if interrupted mid-step]
|
|
retry_count: [0-3 — consecutive auto-retry attempts, reset to 0 on success]
|
|
```
|
|
|
|
### Examples
|
|
|
|
```
|
|
flow: greenfield
|
|
step: 3
|
|
name: Plan
|
|
status: in_progress
|
|
sub_step: 4 — Architecture Review & Risk Assessment
|
|
retry_count: 0
|
|
```
|
|
|
|
```
|
|
flow: existing-code
|
|
step: 2
|
|
name: Test Spec
|
|
status: failed
|
|
sub_step: 1b — Test Case Generation
|
|
retry_count: 3
|
|
```
|
|
|
|
### State File Rules
|
|
|
|
1. **Create** on the first autopilot invocation (after state detection determines Step 1)
|
|
2. **Update** after every change — this includes: batch completion, sub-step progress, step completion, session boundary, failed retry, or any meaningful state transition. The state file must always reflect the current reality.
|
|
3. **Read** as the first action on every invocation — before folder scanning
|
|
4. **Cross-check**: verify against actual `_docs/` folder contents. If they disagree, trust the folder structure and update the state file
|
|
5. **Never delete** the state file
|
|
6. **Retry tracking**: increment `retry_count` on each failed auto-retry; reset to `0` on success. If `retry_count` reaches 3, set `status: failed`
|
|
7. **Failed state on re-entry**: if `status: failed` with `retry_count: 3`, do NOT auto-retry — present the issue to the user first
|
|
8. **Skill-internal state**: when the active skill maintains its own state file (e.g., document skill's `_docs/02_document/state.json`), the autopilot's `sub_step` field should reflect the skill's internal progress. On re-entry, cross-check the skill's state file against the autopilot's `sub_step` for consistency.
|
|
|
|
## State Detection
|
|
|
|
Read `_docs/_autopilot_state.md` first. If it exists and is consistent with the folder structure, use the `Current Step` from the state file. If the state file doesn't exist or is inconsistent, fall back to folder scanning.
|
|
|
|
### Folder Scan Rules (fallback)
|
|
|
|
Scan `_docs/` to determine the current workflow position. The detection rules are defined in each flow file (`flows/greenfield.md` and `flows/existing-code.md`). Check the existing-code flow first (Step 1 detection), then greenfield flow rules. First match wins.
|
|
|
|
## Re-Entry Protocol
|
|
|
|
When the user invokes `/autopilot` and work already exists:
|
|
|
|
1. Read `_docs/_autopilot_state.md`
|
|
2. Cross-check against `_docs/` folder structure
|
|
3. Present Status Summary (use the active flow's Status Summary Template)
|
|
4. If the detected step has a sub-skill with built-in resumability, the sub-skill handles mid-step recovery
|
|
5. Continue execution from detected state
|
|
|
|
## Session Boundaries
|
|
|
|
After any decompose/planning step completes, **do not auto-chain to implement**. Instead:
|
|
|
|
1. Update state file: mark the step as completed, set current step to the next implement step with status `not_started`
|
|
- Existing-code flow: After Step 4 (Decompose Tests) → set current step to 5 (Implement Tests)
|
|
- Existing-code flow: After Step 8 (New Task) → set current step to 9 (Implement)
|
|
- Greenfield flow: After Step 5 (Decompose) → set current step to 6 (Implement)
|
|
2. Present a summary: number of tasks, estimated batches, total complexity points
|
|
3. Use Choose format:
|
|
|
|
```
|
|
══════════════════════════════════════
|
|
DECISION REQUIRED: Decompose complete — start implementation?
|
|
══════════════════════════════════════
|
|
A) Start a new conversation for implementation (recommended for context freshness)
|
|
B) Continue implementation in this conversation
|
|
══════════════════════════════════════
|
|
Recommendation: A — implementation is the longest phase, fresh context helps
|
|
══════════════════════════════════════
|
|
```
|
|
|
|
These are the only hard session boundaries. All other transitions auto-chain.
|