npm package: @fuiste/iterate
Description: Local-first issue tracker for long-horizon agent workflows.
Author: Fuiste
Latest version: 0.1.0

# `@fuiste/iterate`

`@fuiste/iterate` is a local-first issue tracker for long-horizon agent workflows. It is designed for a Ralph-loop style workflow where a human frames a large initiative, approves the planning and documentation shape, and agents repeatedly pick up ready tasks, report progress, and move work toward verification.

The package is built with Bun, TypeScript, and Effect. It exposes a JSON-first CLI for agent harnesses and a lightweight local web UI for visualizing project status.

## Goals

- Keep the coordination surface simple enough for agents to use reliably.
- Preserve structure for long-running initiatives: docs, implementation, tests, and verification.
- Support local-first development today while keeping a clean backend abstraction for future hosted coordination.
- Integrate with Cursor and similar tools through an `AGENTS.md` contract installed by the CLI.

## Install

Requires Bun `1.3+`.

```bash
bun add -g @fuiste/iterate
# or
npm install -g @fuiste/iterate
```

You can also run it without a global install:

```bash
bunx @fuiste/iterate init --json
# or
npx @fuiste/iterate init --json
```

## Development

```bash
bun install
bun run check
bun test
bun run build
```

## CLI

```bash
iterate init --json
iterate plan --title "Build iterate" --prompt "Create a local-first issue tracker for async agents." --actor planner --json
iterate ready --json
iterate claim <task-id> --actor cursor-agent --json
iterate update <task-id> --status blocked --note "Waiting on review." --json
iterate close <task-id> --verified --note "Validated against the initiative." --json
iterate board --json
iterate ui --port 3000
iterate install-agent-instructions --json
```

## Ralph Loop Workflow

1. Initialize the workspace.

```bash
iterate init --json
```

2. Create an initiative from a large prompt.

```bash
iterate plan \
  --title "Ship async agent issue tracker" \
  --prompt "Build a local-first issue tracker npm package for long-running agent workflows, with docs, implementation tasks, test gates, and a lightweight status UI." \
  --actor planner \
  --json
```

3. Let agents pick up ready work.

```bash
iterate ready --json
iterate claim <task-id> --actor cursor-agent --json
```

4. Record progress and evidence.

```bash
iterate update <task-id> \
  --status in_progress \
  --note "Implemented the SQLite repository and claim semantics." \
  --artifact-kind file \
  --artifact-value src/backend/sqlite.ts \
  --artifact-label "Repository implementation" \
  --actor cursor-agent \
  --json
```

5. Close and verify work.

```bash
iterate close <task-id> --verified --note "Reviewed against the approved initiative." --actor reviewer --json
```

6. Inspect the project board.

```bash
iterate board --json
iterate ui
```

## What `plan` Creates

Each initiative is materialized as a small workflow graph:

- a requirements and success-criteria task
- a design task
- an implementation task
- a unit test task
- an integration or workflow test task
- a verification task

Dependencies ensure agents can always ask the system what is ready next.

## Web UI

`iterate ui` launches a minimal local status board backed by the same application services as the CLI. It is intentionally read-mostly in v1 and focuses on:

- initiative summaries
- task columns by effective status
- blockers
- claims
- verification progress

## `AGENTS.md` Integration

`iterate init` and `iterate install-agent-instructions` install an `AGENTS.md` block that tells agents how to:

- initialize the tracker
- discover ready work
- claim exactly one task at a time
- record notes and artifacts
- close and verify tasks

## Architecture

- `src/domain`: domain types, schemas, and workflow rules
- `src/application`: Effect use-cases over the repository port
- `src/backend`: backend interface plus SQLite implementation
- `src/commands`: CLI parsing and render helpers
- `src/docs`: workspace paths and `AGENTS.md` instruction generation
- `src/ui`: lightweight local web UI
- `test`: domain, backend, CLI, and UI coverage

## Notes

- Storage is local-first in v1, using SQLite under `.iterate/iterate.sqlite`.
- The repository is designed behind an interface so a hosted backend can be added later.
- The CLI JSON output is intended to be stable and easy for agents to consume.