# Steering a Running Project

The autobuilder runs autonomously, but you can steer its direction at any time without stopping it.

## Quick Reference

| Goal | File | Action |
|---|---|---|
| Report bug or request feature | `.autobuilder/backlog.md` | Write (consumed once, highest priority) |
| Change initiative scope | `.autobuilder/initiatives/<active>/spec.md` | Edit in place |
| Add constraint | `.autobuilder/initiatives/<active>/constraints.md` | Append |
| Update project context | `.autobuilder/PRODUCT.md` | Edit (exists after 2nd initiative) |
| Change review behavior | `.autobuilder/config.yaml` | Edit (hot-reloadable) |
| Check current status | `.autobuilder/status.md` | Read |
| See all work | `.autobuilder/initiatives/` | Browse |
| View iteration history | `.autobuilder/journal.jsonl` | Read |
| Stop the loop | `.autobuilder/stop` | `touch .autobuilder/stop` |

## Backlog — One-Shot Feedback

The highest-priority steering mechanism. Write anything to `.autobuilder/backlog.md` and the next iteration will read it as its top priority:

```bash
echo "The login page shows a blank white screen on Safari" > .autobuilder/backlog.md
```

**Behavior:**
- The file is consumed (read and deleted) at the start of the next iteration
- Its content appears at the top of the agent prompt, before all other context
- The agent treats backlog items as the highest priority override
- Only one backlog file exists at a time (writing a new one replaces the previous)

**Use cases:**
- Report a critical bug that needs immediate attention
- Request a specific feature or change
- Provide feedback on the last iteration's work
- Override the agent's current direction

## Editing the Initiative Spec

The initiative spec (`spec.md`) is the agent's primary scope document. Edit it to change what the agent focuses on:

```bash
# Open in your editor
vim .autobuilder/initiatives/0001-my-app/spec.md
```

Changes take effect on the next iteration. The agent re-reads the spec every iteration.

**Tips:**
- Be specific about what you want. "Make the dashboard better" is weak; "Add a real-time P&L chart to the dashboard header showing today's gains/losses" is strong.
- Use acceptance criteria to define "done"
- Remove completed objectives to prevent the agent from re-reviewing them

## Adding Constraints

Constraints are hard rules the agent must follow. Append to `constraints.md`:

```bash
cat >> .autobuilder/initiatives/0001-my-app/constraints.md << 'EOF'

## Performance
- All pages must score 90+ on Lighthouse Performance
- No page should take more than 2 seconds to become interactive
EOF
```

## Changing Review Configuration

Edit `.autobuilder/config.yaml` to change review behavior. Changes are hot-reloadable:

```bash
# Shift to more feature discovery
sed -i 's/review_polish_weight: 0.9/review_polish_weight: 0.5/' .autobuilder/config.yaml
```

See [Configuration](configuration.md) for all options.

## Monitoring

### Status File

`.autobuilder/status.md` shows the current state:

```markdown
# Autobuilder Status

**Project:** my-app
**Iteration:** 42
**Phase:** building
**Details:** Running builder agent (phases: review, plan, execute)...
**Updated:** 2025-01-15 14:32:00
```

### Loop Log

Real-time daemon log:

```bash
tail -f .autobuilder/loop.log
```

### Journal

Structured iteration history:

```bash
# Last 5 iterations
tail -5 .autobuilder/journal.jsonl | python3 -m json.tool
```

### Memory Index

The agent's context summary:

```bash
cat .autobuilder/memory-index.md
```

## Stopping and Restarting

### Graceful Stop

```bash
touch .autobuilder/stop
```

The daemon finishes the current iteration and exits. The `stop` file is deleted automatically.

### Force Stop

```bash
kill $(cat .autobuilder/daemon.pid)
```

### Restart

Simply re-run the daemon command. It will:
1. Kill any previous daemon (via PID file)
2. Pick up where it left off (task state is persistent)
3. Read the latest config

```bash
python3 skills/build-feature/builder_loop.py --start my-app
```

## Creating a New Initiative

Use the `create-initiative` skill to add a follow-up initiative:

1. The skill creates a new directory (e.g., `0002-redesign/`)
2. Writes a new `spec.md` based on your requirements
3. Creates/updates `PRODUCT.md` with cross-initiative context
4. Sets the new initiative as active

The previous initiative's tasks remain accessible for reference.
