Nanocycles

The Nanocycle is the fundamental unit of work in Tevis—a structured development cycle that takes your requirements from plan to merged code.

What is a Nanocycle?

A nanocycle is a complete development iteration with:

Clear scope — Defined features and tasks
AI planning — Structured plan generation
Parallel execution — Multiple TPUs working simultaneously
Human review — Approval gates throughout
Clean completion — Merged, tested, documented

┌─────────────────────────────────────────────────────────────┐
│                      NANOCYCLE NC-007                        │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  PLAN          EXECUTE         REVIEW          CLOSE        │
│  ━━━━━         ━━━━━━━         ━━━━━━          ━━━━━        │
│  │             │               │               │            │
│  ├─ Draft      ├─ TPU-1       ├─ Code review  ├─ Merge     │
│  ├─ Review     ├─ TPU-2       ├─ Tests pass   ├─ Cleanup   │
│  └─ Approve    ├─ TPU-3       └─ Approve      └─ Archive   │
│                └─ Hold points                               │
│                                                              │
└─────────────────────────────────────────────────────────────┘

Nanocycle Lifecycle

1. Draft Phase

You describe what you want to build:

# Nanocycle Description

Add user settings page with:
- Profile editing (name, email, avatar)
- Password change flow
- Notification preferences
- Theme selection (dark/light)
- Account deletion option

Tevis generates a structured plan with features and tasks.

2. Ready Phase

You review and approve the plan:

nanocycle: NC-007
title: User Settings Page
status: ready

features:
  - name: settings-api
    tasks:
      - T001: Create settings endpoints
      - T002: Add validation schemas
      - T003: Write API tests

  - name: settings-ui
    tasks:
      - T004: Create SettingsPage component
      - T005: Add profile editing form
      - T006: Add password change modal
      - T007: Add notification toggles
      - T008: Add theme selector
      - T009: Add delete account flow

  - name: integration
    tasks:
      - T010: Wire UI to API
      - T011: Add E2E tests

3. In Progress Phase

TPUs execute tasks in parallel:

Feature: settings-api
├── TPU-1: T001 [████████████] Complete
├── TPU-1: T002 [████████░░░░] In Progress
└── TPU-1: T003 [░░░░░░░░░░░░] Pending

Feature: settings-ui
├── TPU-2: T004 [████████████] Complete
├── TPU-2: T005 [██████░░░░░░] In Progress
└── ...

Feature: integration (blocked until dependencies complete)

4. Completed Phase

All tasks done, ready for review:

All features complete
Tests passing
Code ready for review

5. Closing Phase

Final review and merge:

Generate closure summary
Create PR
Run final tests
Merge to main

6. Archived Phase

Nanocycle complete and archived:

Artifacts preserved in knowledge base
Memory extracted
Branches cleaned up
PR merged

Nanocycle States

State	Description	Actions Available
`draft`	Plan being generated	Edit scope, regenerate
`ready`	Plan approved, ready to run	Execute, edit plan
`in_progress`	TPUs actively working	Monitor, hold points
`completed`	Execution done	Review, request changes
`closing`	Closure in progress	Wait
`closed`	PR created, ready to merge	Merge, archive
`archived`	Complete, PR merged	View history
`failed`	Execution failed	Diagnose, retry

Features and Tasks

Features

Features are logical groupings of related tasks:

features:
  - name: auth-backend        # Backend auth logic
  - name: auth-frontend       # UI components
  - name: auth-integration    # Wiring and tests

Features can have dependencies:

features:
  - name: database-setup

  - name: api-endpoints
    depends_on: [database-setup]

  - name: ui-components
    depends_on: [api-endpoints]

Tasks

Tasks are atomic units of work:

tasks:
  - id: T001
    subject: Create User model
    description: Define SQLAlchemy User model with email, password_hash, created_at

  - id: T002
    subject: Add password hashing
    description: Implement bcrypt password hashing utility
    depends_on: [T001]

Task properties:

id — Unique identifier (T001, T002, etc.)
subject — Brief description
description — Detailed requirements
depends_on — Task dependencies
status — pending, in_progress, completed, failed

Execution Model

Parallel Execution

TPUs work on independent features simultaneously:

Time →
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  TPU-1: [auth-backend ████████████████████]                 │
│                                                             │
│  TPU-2: [auth-frontend ████████████████████████████]        │
│                                                             │
│  TPU-3:                      [auth-integration ████████████]│
│         ↑                     ↑                             │
│         Start                 Unblocked when deps complete  │
└─────────────────────────────────────────────────────────────┘

Task Flow

Within a feature, tasks execute sequentially respecting dependencies:

T001 (Create model)
  ↓
T002 (Add validation) ─── depends_on: T001
  ↓
T003 (Write tests) ────── depends_on: T002

Hold Points

Execution pauses at hold points:

hold_points:
  - type: file_deletion
    file: src/old-auth.py
    reason: "About to delete existing auth implementation"

  - type: ambiguous_requirement
    task: T005
    question: "Should password require special characters?"

Creating Nanocycles

From Mission Control

Open active session
Click "New Nanocycle"
Describe requirements
Review generated plan
Approve to start execution

From CLI

# Create with description
tevis nanocycle create --description "Add user settings page"

# Create from file
tevis nanocycle create --from-file requirements.md

# Create and auto-approve (use with caution)
tevis nanocycle create --description "..." --auto-approve

From Planning Context

If your microcycle specifies planned nanocycles:

# Microcycle: Week 1

## Planned Nanocycles
1. NC-007: User settings page
2. NC-008: Email notifications
3. NC-009: API rate limiting

Tevis can auto-populate nanocycle descriptions from your planning context.

Nanocycle Sizing

Ideal Size

A well-sized nanocycle has:

5-15 tasks — Enough for meaningful progress
2-4 features — Logical groupings
4-8 hour execution — Completes in a reasonable time
Clear scope — Well-defined boundaries

Too Small

❌ NC-007: Fix typo in README
   - Single trivial task
   - Overhead exceeds value
   - Better as quick fix

Too Large

❌ NC-007: Rebuild entire authentication system
   - 50+ tasks
   - Multiple days execution
   - Too many unknowns
   - Hard to review

Just Right

✅ NC-007: Add password reset flow
   - Feature 1: Reset API endpoints (3 tasks)
   - Feature 2: Email templates (2 tasks)
   - Feature 3: Reset UI flow (4 tasks)
   - Feature 4: Integration tests (2 tasks)
   - Total: 11 tasks, clear scope

Nanocycle Artifacts

Each nanocycle produces artifacts stored in the knowledge base:

kb/nanocycles/NC-007/
├── 01_Planning/
│   ├── PLAN.md              # Approved plan
│   └── requirements.md      # Original requirements
├── 02_Execution/
│   ├── cycle.json           # Machine-readable plan
│   ├── execution.log        # Execution logs
│   └── features/
│       ├── settings-api/
│       │   └── progress.txt
│       ├── settings-ui/
│       │   └── progress.txt
│       └── integration/
│           └── progress.txt
└── 03_Closure/
    ├── CLOSURE_OVERVIEW.md  # Summary
    └── pr_url.txt           # Link to PR

Monitoring Nanocycles

Status View

tevis nanocycle status NC-007

# Output
Nanocycle: NC-007
Title: User Settings Page
Status: in_progress
Progress: 7/11 tasks (64%)

Features:
  settings-api   [████████████] Complete
  settings-ui    [████████░░░░] 75%
  integration    [████░░░░░░░░] 33%

Active TPUs: 2
Hold Points: 0
ETA: ~45 minutes

Consciousness Stream

Real-time execution output streams to Mission Control:

[14:32:15] TPU-2 | Starting T006: Add password change modal
[14:32:18] TPU-2 | Creating file: src/components/PasswordChangeModal.tsx
[14:32:25] TPU-2 | Adding form validation
[14:32:32] TPU-2 | Writing component tests
[14:32:45] TPU-2 | Task T006 complete

Best Practices

Write Clear Requirements

❌ "Add settings"

✅ "Add user settings page with:
    - Profile editing (name, email, avatar)
    - Password change with current password verification
    - Notification preferences (email, push toggles)
    - Theme selection (dark/light/system)
    - Account deletion with confirmation"

Review Plans Before Approving

Don't auto-approve. Check:

All requirements addressed
Tasks are appropriately sized
Dependencies make sense
Scope is achievable

Monitor Execution

Don't start and walk away for hours. Check periodically:

Progress is steady
No stuck tasks
No accumulating errors

Review Thoroughly

Before closing:

Read generated code
Run tests locally
Check for security issues
Verify edge cases

What is a Nanocycle?​

Nanocycle Lifecycle​

1. Draft Phase​

2. Ready Phase​

3. In Progress Phase​

4. Completed Phase​

5. Closing Phase​

6. Archived Phase​

Nanocycle States​

Features and Tasks​

Features​

Tasks​

Execution Model​

Parallel Execution​

Task Flow​

Hold Points​

Creating Nanocycles​

From Mission Control​

From CLI​

From Planning Context​

Nanocycle Sizing​

Ideal Size​

Too Small​

Too Large​

Just Right​

Nanocycle Artifacts​

Monitoring Nanocycles​

Status View​

Consciousness Stream​

Best Practices​

Write Clear Requirements​

Review Plans Before Approving​

Monitor Execution​

Review Thoroughly​