Skip to content

guide.md

Latest commit

 

History

History
398 lines (284 loc) · 10.9 KB

guide.md

File metadata and controls

398 lines (284 loc) · 10.9 KB
Raw

Operator guide

This guide covers the normal Execraft workflow from project onboarding through task completion. It intentionally avoids duplicating the detailed contracts in the topic documents linked throughout the guide.

1. Check the installation

execraft home
execraft doctor

For execution-agent/runtime checks:

execraft agents status --project <project-id>
execraft agents doctor --project <project-id> --smoke-test

A project is not ready for autonomous orchestration until its descriptor, repositories, verification commands, and at least one enabled execution agent are usable.

2. Onboard a project

Existing source tree

Inspect the source without modifying it:

cd /path/to/project

execraft project inspect
execraft init --dry-run

Create and register the descriptor:

execraft init --template standard

Validate the result:

execraft project validate <project-id>
execraft project doctor <project-id>

If a descriptor already exists, register or bind it instead of creating a new one:

execraft project register \
  --descriptor /path/to/project.yaml \
  --source /absolute/path/to/project-root

# or
execraft project bind <project-id> --source /absolute/path/to/project-root

Host-specific paths belong in local registration state, not in the portable project descriptor.

Greenfield project

Preview before creating files:

execraft new sample-service --template python-service --dry-run

Then apply:

execraft new sample-service --template python-service --yes

For onboarding internals, see onboarding-architecture.md and control-plane-home.md.

3. Start a task

For most work, use the composed command:

cd /path/to/project
execraft start "Add request tracing to the API"

The preview is side-effect free:

execraft start "Add request tracing" --dry-run --json

Useful controls:

# Local deterministic planning
execraft start "Add request tracing" --planner local

# Require agent-backed planning
execraft start "Add request tracing" --planner agent --require-agent

# Explicit multi-repository scope
execraft start "Update authentication" --repositories backend frontend

# Reuse an existing plan
execraft start --plan-file ./PLAN.md --planner local

execraft start creates or reuses the project, task dossier, workspace, and validated execution graph. Use the lower-level commands only when you need explicit control over individual lifecycle stages.

See start-workflow.md and task-definition-import.md.

4. Create a task manually

A manual task dossier can be useful for reviewed or imported plans:

execraft task new feature_auth \
  --project sample \
  --title "Add authentication" \
  --brief "Add token-based authentication and preserve current API behavior." \
  --repositories backend frontend

Preview the transaction first when needed:

execraft task new feature_auth \
  --project sample \
  --title "Add authentication" \
  --brief "Add token-based authentication." \
  --dry-run --json

Import existing task documents with --brief-file, --plan-file, or --plan-graph-file rather than copying them into generated state manually.

Inspect task state with:

execraft task status feature_auth --project sample
execraft task sync-status feature_auth --project sample

5. Work in an isolated workspace

Create the workspace:

execraft workspace start feature_auth \
  --workspace-root ~/workspace/ai-workspaces/feature_auth \
  --policy workspace-write

Inspect and verify it:

execraft workspace status feature_auth
execraft workspace verify feature_auth --profile focused

Open the generated multi-root VS Code workspace:

execraft code feature_auth

Use the generated Workspace root as the control surface. Source edits belong in the task worktrees, while generated agent/runtime configuration, skills, and the repository catalog live in the workspace shell.

After changing project or runtime/agent configuration:

execraft workspace refresh feature_auth

Do not edit generated .agents, .claude, .codex, .opencode, .vscode, AGENTS.md, or CLAUDE.md files directly.

See workspace-lifecycle-safety.md.

6. Configure verification and execution agents

Verification commands are defined by the project and are always explicit. Profiles are cumulative:

cheap -> focused -> integration -> full

Run a focused check from the workspace with:

execraft workspace verify feature_auth --profile focused

Execution-agent health is separate from project verification:

execraft agents status --project sample
execraft agents doctor --project sample
execraft agents doctor --project sample --agent codex --smoke-test

Use project policy to control capabilities, weights, complexity limits, concurrency, and agent-profile preferences. See execution_policy.md, quality-checks.md, and satellite_nodes.md.

7. Run the orchestrator

The orchestrator executes the validated PLAN.graph.yaml, not free-form plan text.

Initialize state:

execraft orchestrate init \
  --project sample \
  --task-id feature_auth \
  --plan-file projects/sample/tasks/feature_auth/PLAN.graph.yaml

Inspect before running:

execraft orchestrate status --project sample --task-id feature_auth
execraft orchestrate explain --project sample --task-id feature_auth

Run:

execraft orchestrate run --project sample --task-id feature_auth

Useful diagnostics:

execraft orchestrate trace --project sample --task-id feature_auth --limit 20
execraft orchestrate usage --project sample --task-id feature_auth
execraft orchestrate context \
  --project sample --task-id feature_auth --package-id implementation

If an execution agent or runtime is temporarily unavailable, normal orchestration can wait and retry according to project policy. Genuine unsafe or unresolved conditions move to an explicit operator or Supervisor recovery path.

See orchestration-data-flow.md, supervisor.md, and recovery_playbooks.md.

8. Control scope and scheduling

Agents do not receive unrestricted write authority. The orchestrator validates repository and path scope before accepting mutations, and it protects cross-package isolation during retries and recovery.

Inspect a scope issue with:

execraft orchestrate scope \
  --project sample --task-id feature_auth --package-id implementation

Work Package policy and agent-profile preferences can be changed without editing live state files:

execraft orchestrate policy \
  --project sample --task-id feature_auth --package-id implementation \
  --role implement --agent codex --agent claude

See scope-checks.md and execution_policy.md.

9. Use the local GUI

Launch the control center:

execraft gui

Open a specific task:

execraft gui --project sample --task-id feature_auth

The GUI is a local operator surface for onboarding, plan inspection, orchestration, agent health, workspace changes, commits, logs, and recovery. It does not replace the deterministic backend checks.

See gui-onboarding.md, gui-task-lifecycle.md, gui-workbench.md, and agent_console.md.

10. Synchronize long-running repositories

When a task must incorporate upstream work, insert an explicit synchronization Work Package rather than merging ad hoc inside an agent session:

execraft task sync-before feature_auth \
  --project sample \
  --before deploy \
  --repositories backend frontend \
  --source-branch backend=feature/api-cleanup

The synchronization flow records divergence, conflict handling, verification, and integration state as a durable transaction.

See repository-synchronization.md.

11. Replan safely

Stage a change request without replacing the accepted task definition:

execraft task replan feature_auth \
  --project sample \
  --request "Split the migration into a compatibility phase and a cleanup phase"

Review the candidate before applying it. Replanning preserves provenance and started-work constraints rather than silently rewriting the active plan.

See task-replanning.md.

12. Complete and archive

Check readiness first:

execraft task complete feature_auth --project sample --check

Archive and close:

execraft task complete feature_auth --project sample --archive

Verify the resulting archive:

execraft archive list --project sample
execraft archive show feature_auth --project sample
execraft archive verify feature_auth --project sample

Workspace cleanup remains policy-gated after completion. See task-completion.md and workspace-finalization.md.

Troubleshooting checklist

Symptom First check
Project is registered but not ready execraft project doctor <project-id>
Execution agent is skipped or unavailable execraft agents status --project <project-id>
Live agent/runtime call fails execraft agents doctor --project <project-id> --smoke-test
Workspace looks stale execraft workspace refresh <task-id>
Verification does not run check verification.yaml and the selected profile
Orchestration is blocked execraft orchestrate explain --project <project-id> --task-id <task-id>
Need exact prior agent activity execraft orchestrate trace --project <project-id> --task-id <task-id>
Scope expansion is blocked inspect scope-checks.md before accepting recovery
Task cannot close execraft task complete <task-id> --project <project-id> --check

Advanced topics

Use the topic docs instead of extending this guide with implementation detail: