Astra Dev

Astra Dev

Use this as an engineering state machine, not as a project encyclopedia. The loop is:

Explore -> Integrate -> Execute -> Verify
             ^            |
             |            v
        Re-open only on explicit invalidation

The goal is to identify the owning crate, preserve the intent of existing edits, convert known facts into an executable checklist, change the smallest correct surface, and verify with the narrowest gate that proves the behavior.

Hard Rule: Structured Control Flow

Do not add production control flow based on natural-language text matching. Safety, admission, routing, blocking, retry, recovery, evaluation, and state transitions must use typed facts: enums, ErrorKind, result_class, exit_semantics, structured tool-result JSON, protocol parsers, AST/token parsers, or exact machine-owned sentinel fields.

Allowed text matching is rare: UI display/search, tests of rendered text, or legacy protocol fallback named with a fallback suffix. A fallback must not be the primary safety/admission/blocking/evaluation decision.

Hard Rule: One Owner, One Wired Path

Before adding a type, service, registry, state machine, observer, table, parser, or compatibility layer:

1. Search for the existing owner of the fact or lifecycle and name it in the execution record.
2. Trace the real product entrypoint to that owner. Unit tests and constructors called only by tests are not wiring evidence.
3. Extend the owner when possible. A new owner is justified only by a distinct authority, deployment, security, or resource-lifecycle boundary.
4. If replacing a path, migrate its callers and delete the old implementation, old state/table/shim, and tests that only exercised the old island in the same change. Do not keep code for unspecified "future extensibility".
5. Report the complexity delta: implementations, status vocabularies, writers, tables, compatibility paths, and net code. Added tests do not cancel out a second source of truth.

Lifecycle status is owned by the producer that performs the transition. Put the canonical typed projection on that producer and make CLI, server, UI, persistence, and wake logic consume it. Consumers must not independently re-count child states or translate transport events into lifecycle truth. A fixed-size fanout is one work unit: individual child events are progress, and only the canonical group terminal transition may authorize parent synthesis.

For persistence, a mock-only test is insufficient. Prove schema bootstrap, query/transaction semantics, failure behavior, and the public caller against the real configured database whenever the change crosses that boundary.

Task

$ARGUMENTS

Phase 1: Explore Task (finish in about 3 minutes)

1. Run git status --short.
2. If focus files are known, inspect both staged and unstaged diffs for them, then run git log --oneline -10 -- <FILES>.
3. Read only the owning module and the immediate caller/callee needed to explain the change. Use the Ownership Map below.
4. State the task location in one line:

Task: <behavior to change>
Owner: <crate/module>
Boundary: <caller -> owner -> persistence/tool/prompt/test surface>
Prior intent: <what the current uncommitted diff appears to be preserving>

Rules:

• Treat uncommitted changes as intentional until disproven.
• If you cannot explain the intent of a previous edit, inspect more before replacing it.
• Do not read every design document up front; load context only when it changes a decision.
• Stop exploring when you can name the owner, contract boundary, and intended behavior.

Phase 2: Integrate Findings

Before editing, convert discoveries into a compact execution record. Do this even when the task is small; keep it brief for one-file fixes.

Facts:
- <session-stable facts: owner, files, functions, invariants, review findings>

Assumptions:
- <claims that tests or compilation must confirm>

Edit checklist:
- [ ] <file>: <region/function>; <change>; <invariant preserved>

Verification:
- <narrowest command(s) proving the behavior>

Re-open conditions:
- <what would justify returning to exploration>

Use an explicit plan before editing when the task touches more than 3 files, more than 1 crate, runtime plus services, persistence schema, prompt/tool visibility, delegation, or any user-visible workflow. If the host supports plan mode, enter it for those cases. Otherwise keep the checklist current.

Information durability:

• Session-stable: user goal, prior edit intent, owning file/module, function names, contracts, review findings, and invariants until an invalidation occurs.
• Volatile: line numbers after edits, test output, command output, branch status, diff context, runtime state, and anything another process may have changed.
• Do not re-grep a session-stable fact just because it came from a previous review or checklist.

Re-open exploration only when one of these happens:

• Target text or local context no longer matches.
• A patch/edit fails.
• Compile or test output contradicts the model.
• The user changes the goal or scope.
• The worktree changes outside your edits.
• A contract boundary is unknown and affects the edit.

Phase 3: Execute Checklist

1. Work checklist items in dependency order.
2. Immediately before each edit, read the smallest complete local context needed to patch safely. Usually this is 20-80 lines around the target, not a whole file.
3. Do not use broad grep/glob during execution unless it tests a specific hypothesis from the checklist or a re-open condition fired.
4. Edit the owning module first. Change callers only when the contract changes.
5. For Rust code, after each logical edit batch run a narrow compile gate:

cargo check -p <crate>

6. Add or update tests at the same layer as the behavior:

• Pure helper behavior: unit test in the owning crate.
• Runtime/turn behavior: focused runtime or turn-core test.
• Persistence behavior: service/storage test plus DB state assertion where applicable.
• CLI behavior: CLI parser/rendering test or focused command test.
• Skill/docs change: frontmatter/path/stale-reference validation, not a Rust build.

7. If compatibility is explicitly out of scope, delete the obsolete path instead of layering a second model.

Phase 4: Failure Triage

Use the first matching row before widening the search.

Phase 5: Verification Gates

Run make targets and raw cargo commands from the repository root.

Useful focused runtime tests:

Delivery Report

End with:

• Behavior changed, not just files changed.
• Why the final model is simpler or more correct.
• Verification commands and outcomes.
• Skipped checks and residual risk, if any.

Appendix: Ownership Map

Appendix: Astra Invariants

Appendix: Sibling Skills