Skip to main content

Your First Session

This tutorial walks you through a complete Tevis development session—from creating a project to merging your first nanocycle.

What We'll Build​

In this tutorial, you'll use Tevis to build a task management API with:

  • RESTful endpoints for CRUD operations
  • SQLite database persistence
  • Input validation
  • Unit tests

By the end, you'll understand:

  • How to create and configure projects
  • How nanocycles work
  • How to review and approve AI-generated code

Prerequisites​

Ensure you have:

  • Tevis installed
  • Services running (tevis-local serve and mc start)
  • Mission Control open at http://localhost:8083

Step 1: Create a Project​

Using Mission Control​

  1. Open Mission Control at http://localhost:8083
  2. In the Projects panel, click "+ New Project"
  3. Fill in the project details:
FieldValue
NameTask Manager
Slugtask-manager
DescriptionA simple task management API
Repository(leave empty for now)
  1. Click "Create"

Using CLI (Alternative)​

tevis init task-manager --description "A simple task management API"

Step 2: Set Up Planning Context​

Before creating a nanocycle, let's establish the project context.

Create Knowledge Base Files​

Navigate to your project's knowledge base:

cd ~/.tevis/accounts/personal/projects/task-manager/kb

Create PROJECT.md:

# Task Manager

A simple task management API for learning Tevis.

## Tech Stack
- Python 3.11+
- FastAPI
- SQLite
- Pydantic for validation

## API Design
- RESTful conventions
- JSON responses
- Proper HTTP status codes
- Input validation on all endpoints

## Code Standards
- Type hints everywhere
- Docstrings for public functions
- Unit tests for all endpoints

This context helps Tevis understand your project conventions.

Step 3: Start a Session​

  1. In Mission Control, click on "Task Manager" project
  2. Click "New Session" in the Sessions panel
  3. A new session is created and becomes active

The session represents your current work context. All nanocycles will be created within this session.

Step 4: Create Your First Nanocycle​

Define the Scope​

  1. In the active session, click "+ New Nanocycle"
  2. In the planning wizard, describe what you want to build:
Build a task management API with:

1. Task model with: id, title, description, status (todo/in_progress/done), created_at, updated_at
2. SQLite database setup with async support
3. CRUD endpoints:
   - GET /tasks - List all tasks (with optional status filter)
   - GET /tasks/{id} - Get single task
   - POST /tasks - Create task
   - PUT /tasks/{id} - Update task
   - DELETE /tasks/{id} - Delete task
4. Pydantic models for request/response validation
5. Unit tests for all endpoints
  1. Click "Generate Plan"

Review the Plan​

Tevis generates a structured plan with:

nanocycle: NC-001
title: "Task Management API - Core Implementation"

features:
  - name: database-setup
    tasks:
      - T001: Create SQLite database module
      - T002: Define Task model with SQLAlchemy
      - T003: Add database initialization

  - name: api-endpoints
    tasks:
      - T004: Create FastAPI app structure
      - T005: Implement GET /tasks endpoint
      - T006: Implement GET /tasks/{id} endpoint
      - T007: Implement POST /tasks endpoint
      - T008: Implement PUT /tasks/{id} endpoint
      - T009: Implement DELETE /tasks/{id} endpoint

  - name: validation-tests
    tasks:
      - T010: Add Pydantic request/response models
      - T011: Write unit tests for all endpoints

Review carefully:

  • Are all requirements covered?
  • Is the scope appropriate?
  • Are there any missing pieces?
  1. If satisfied, click "Approve Plan"
Plan Modifications

If the plan needs changes, click "Request Revision" and describe what to modify. Tevis will regenerate the plan.

Step 5: Watch Execution​

Once approved, Tevis begins execution:

Execution Dashboard​

The Mission Control interface shows:

NC-001: Task Management API
Status: IN_PROGRESS

┌─ Feature: database-setup ────────────────────┐
│ TPU-1 | ████████████░░░░ | T001-T003         │
└──────────────────────────────────────────────┘

┌─ Feature: api-endpoints ─────────────────────┐
│ TPU-2 | ██████░░░░░░░░░░ | T004-T009         │
└──────────────────────────────────────────────┘

┌─ Feature: validation-tests ──────────────────┐
│ Pending... (waiting for dependencies)        │
└──────────────────────────────────────────────┘

Consciousness Stream​

The consciousness stream shows real-time AI activity:

[10:32:15] TPU-1 | Starting task T001: Create SQLite database module
[10:32:18] TPU-1 | Creating file: src/database.py
[10:32:25] TPU-1 | Task T001 complete
[10:32:26] TPU-1 | Starting task T002: Define Task model
...

Hold Points​

Certain events trigger hold points where execution pauses for your review:

  • File deletions
  • Configuration changes
  • Test failures
  • Ambiguous decisions

When a hold point triggers:

  1. Review the proposed action
  2. Approve to continue, or
  3. Modify with feedback, or
  4. Reject to skip

Step 6: Review Results​

When execution completes:

View Generated Files​

src/
├── database.py      # SQLite setup
├── models.py        # SQLAlchemy models
├── schemas.py       # Pydantic schemas
├── main.py          # FastAPI app
└── tests/
    └── test_api.py  # Unit tests

Inspect the Code​

Click any file in Mission Control to see:

  • Full source code with syntax highlighting
  • Diff view showing what was added/modified
  • Line-by-line comments from the AI

Example: Generated API​

src/main.py
from fastapi import FastAPI, HTTPException, Query
from typing import Optional
from .database import get_db, init_db
from .models import Task
from .schemas import TaskCreate, TaskUpdate, TaskResponse

app = FastAPI(title="Task Manager API")

@app.on_event("startup")
async def startup():
    await init_db()

@app.get("/tasks", response_model=list[TaskResponse])
async def list_tasks(status: Optional[str] = Query(None)):
    async with get_db() as db:
        query = db.query(Task)
        if status:
            query = query.filter(Task.status == status)
        return query.all()

@app.get("/tasks/{task_id}", response_model=TaskResponse)
async def get_task(task_id: int):
    async with get_db() as db:
        task = db.query(Task).filter(Task.id == task_id).first()
        if not task:
            raise HTTPException(status_code=404, detail="Task not found")
        return task

# ... additional endpoints

Step 7: Run Tests​

Before approving, verify the code works:

Run Tests Locally​

# Navigate to workspace
cd ~/.tevis-runtime/tpu-repos/nc-001-task-manager

# Install dependencies
pip install -r requirements.txt

# Run tests
pytest tests/ -v

Expected Output​

tests/test_api.py::test_create_task PASSED
tests/test_api.py::test_list_tasks PASSED
tests/test_api.py::test_get_task PASSED
tests/test_api.py::test_update_task PASSED
tests/test_api.py::test_delete_task PASSED
tests/test_api.py::test_task_not_found PASSED

=================== 6 passed in 0.45s ===================

Step 8: Approve and Close​

Final Review Checklist​

Before closing the nanocycle, verify:

  • All tasks completed
  • Tests pass
  • Code follows project conventions
  • No obvious bugs or issues
  • Files are in correct locations

Close the Nanocycle​

  1. In Mission Control, click "Review & Close"
  2. Add any closing notes (optional)
  3. Click "Close Nanocycle"

This triggers:

  • Merging feature branches
  • Creating a PR (if configured)
  • Updating project memory
  • Archiving artifacts

Step 9: Merge to Main​

Review the PR​

If using GitHub integration:

# View the PR
gh pr view NC-001

# Or in Mission Control, click "View PR"

Merge​

# Merge when ready
gh pr merge NC-001 --squash

Or use the Mission Control UI to merge.

What You've Learned​

Congratulations! You've completed your first Tevis session. You now understand:

  1. Projects — How to create and configure Tevis projects
  2. Sessions — Work contexts for nanocycles
  3. Nanocycles — The planning-execution-review workflow
  4. Planning — How to describe work and review plans
  5. Execution — How TPUs work in parallel
  6. Review — How to inspect and approve generated code

Next Steps​

Now that you understand the basics:

Tips for Success​

Write Clear Descriptions​

The clearer your nanocycle description, the better the results:

❌ "Add authentication"

✅ "Add JWT-based authentication with:
    - Login endpoint accepting email/password
    - Access tokens expiring in 15 minutes
    - Refresh tokens expiring in 7 days
    - Password hashing with bcrypt
    - Protected route decorator"

Review Plans Carefully​

The plan is your contract. If something's missing, request revisions before approving.

Use Hold Points​

Don't disable hold points. They're designed to catch issues early.

Check Tests​

Always run tests locally before approving. AI-generated tests might have edge case issues.

Iterate​

Your first nanocycle doesn't have to be perfect. Use subsequent nanocycles to refine and extend.