Agent Workflow (SPTI)

Trovella uses the SPTI workflow (Specify, Plan, Tasks, Implement) for all AI agent development. This is the highest-leverage process decision in the project -- 15--30 minutes of specification saves 1--3 hours of debugging.

The SPTI Workflow

1. Specify

Write a structured specification before the agent touches code. The specification includes:

• What the feature does (acceptance criteria)
• Which packages are affected
• Which existing patterns to follow (reference specific files)
• What is explicitly out of scope

Specifications are written during evening deep work sessions, then dispatched to agents the next morning.

2. Plan

Review the plan in Plan Mode before implementation begins. The agent proposes its approach, file list, and implementation order. The founder reviews for:

• Correct package boundaries (does the agent put code in the right packages?)
• Correct patterns (does it follow existing conventions?)
• Reasonable scope (is it trying to do too much in one session?)

3. Tasks

Decompose the plan into 50--150 line implementation tasks. Each task is a self-contained unit that can be verified independently. Task decomposition is the core skill -- well-scoped tasks produce clean code on first attempt.

4. Implement

Execute tasks sequentially with /clear between tasks. Each task is one agent session. Decisions are persisted in CLAUDE.md files, not conversation history.

Task Sizing

Task size depends on whether the work is greenfield or incremental:

Mode	Scope	Lines	Best For
Greenfield	New feature or capability	500--2000+	Let the agent generate the full vertical slice, smoke test as a whole, then iterate with focused follow-ups
Incremental	Modifying existing code	50--200	Small and focused changes to established patterns

Greenfield tasks with good specifications are ideal for low-attention morning/daytime dispatch. Incremental tasks that touch security-critical code (auth, RLS, payments) require high-attention interactive sessions.

Two Work Modes

The founder's schedule creates two distinct operating modes:

Low-Attention Mode (Mornings and Daytime)

• When: Weekday mornings 6--9am (~2 hours), weekday daytime during day job (~2 hours equivalent, checked every 1--2 hours)
• What: Dispatch pre-planned tasks written the evening before. Review yesterday's PRs. Triage Linear inbox.
• Rule: Only dispatch well-specified tasks. Vague tasks in low-attention mode waste agent time.

High-Attention Mode (Evenings and Weekends)

• When: Weekday evenings 1--3 hours (Mon--Thu, minus one evening off), weekend days 3--6 hours each
• What: Spec writing, complex reviews, architecture decisions, hands-on coding, interactive debugging sessions, PR review of daytime agent output
• Pattern: 90-minute ultradian blocks for deep work -- 90 minutes focused, 15-minute break, then remaining time

The morning/daytime agent babysitting pattern effectively doubles development hours by letting agents implement while the founder focuses on the day job.

Session Discipline

• One session per task. Do not let a session drift into unrelated work.
• /clear between tasks. Fresh context prevents accumulated confusion.
• 5--10 minutes of session prep. Review the spec, identify the files the agent will need, and set expectations.
• Persist decisions in CLAUDE.md, not conversation history. Conversations are ephemeral. CLAUDE.md survives across sessions.

Parallel Agent Development

Multiple agents can work simultaneously using git worktrees:

• Each worktree gets its own filesystem, Docker database, and branch
• Vertical slice task decomposition prevents file conflicts between agents
• PR-per-worktree with squash merge keeps the main branch clean

The monorepo's package structure naturally decomposes into independent work streams. File-based routing combined with feature directories creates non-overlapping file sets.

Scaling: Start with single-agent sequential work. Scale to 2--3 parallel worktree agents as comfort grows. The pnpm global virtual store makes worktree creation take seconds, not minutes.

Mandatory Manual Review

AI agents are never trusted alone for:

• Auth and session handling
• RLS and tenant isolation
• Payments and billing
• Data access control
• Anything in packages/db security layer

The METR research finding is acknowledged: experienced developers were 19% slower with AI despite believing they were 20% faster. Spec-driven discipline is what separates real gains from perceived gains.

Quality Flywheel

Every AI bug becomes one of three things:

1. A CLAUDE.md rule preventing recurrence
2. An ESLint rule catching the pattern at editor time
3. A test case catching the behavior at CI time

After months of development, this flywheel produces tightly-tuned guardrails with consistently correct agent output. The initial investment in CLAUDE.md files and custom ESLint rules pays compound returns.

Cross-Domain References

• Sprint Cadence & Sustainability -- how the two work modes fit into weekly planning
• Conventions -- commit rules, code review process, ticket format
• Delivery -- Quality Gates -- the CI checks agents must pass
• Delivery -- Local CI Parity -- pnpm ci:check that agents run before every commit