Interactive Guide to AI-Driven Software Development

The Core Development Cycle

The foundation of this framework is a continuous cycle of documentation and verification. This ensures the AI agent always has the necessary context to perform tasks accurately. Click on each step to learn more about the specific actions involved.

🚀

1. Initialize

Set up project documentation.

→

📖

2. Act

Read docs before each task.

→

✍️

3. Verify

Update docs & run tests.

Click a step above to see the details here.

Best Practices for a Flexible Framework

To enhance the framework's adaptability and efficiency, several best practices are recommended. These practices focus on automation, configuration, and a pragmatic approach to testing, allowing the framework to be applied to a wide variety of projects with minimal friction.

Use a Single Entry Point

Instead of hardcoding commands, use a single `run.sh` script that acts as a universal interface for common development tasks like linting, testing, and running the application. This script reads from a configuration file to determine the actual commands to execute.

Benefit: This approach decouples the AI agent's logic from the project's specific tooling. The agent can consistently call `./scripts/run.sh test` across different projects, and the script will handle the project-specific implementation.

#!/bin/bash
# scripts/run.sh

TASK=$1
CONFIG_FILE="project-spec.json"

# Read command from JSON config
COMMAND=$(jq -r ".commands.$TASK" $CONFIG_FILE)

if [[ "$COMMAND" == "null" ]]; then
  echo "Task '$TASK' not found in $CONFIG_FILE."
  exit 1
fi

# Execute the command
echo "Executing: $COMMAND"
eval $COMMAND

Externalize Configuration

Store all project-specific paths, commands, and metadata in a `project-spec.json` file. This centralizes configuration and makes the framework adaptable to any project structure without code changes.

Benefit: Allows immediate adaptation to any project’s folder structure, naming conventions, and tooling without modifying the core AI agent framework.

{
  "project_name": "My Awesome App",
  "source_dir": "src",
  "docs": {
    "project": "docs/project.md",
    "context_log": "docs/context_log.md",
    "dev_log": "docs/dev_log.md"
  },
  "commands": {
    "static_check": "npm run lint",
    "unit_test": "npm test",
    "e2e_test": "npm run cypress:run"
  }
}

Make E2E Testing a Goal, Not a Prerequisite

Treat End-to-End (E2E) testing as a milestone to be completed, rather than a blocking requirement from the start. This allows projects to get started quickly while still prioritizing the setup of comprehensive testing.

Suggested Behavior: During the VERIFY stage, if an `e2e_test` command is defined in the configuration, the framework runs it. If not, it logs the absence and marks E2E setup as a pending task.

Benefit: Projects can achieve momentum without being blocked by initial test setup, while ensuring that E2E testing remains an important, tracked deliverable.

Automate Project Initialization

Provide a setup script, like `init-agent-project.sh`, to scaffold the entire documentation and test structure in a single command. This script can create documentation files from templates, seed test scripts with placeholders, and generate the `project-spec.json` file.

Benefit: Radically simplifies project setup, reduces manual error, and ensures consistency across all projects managed by the AI agent.

#!/bin/bash
# init-agent-project.sh

# Create doc files from templates
mkdir -p docs
touch docs/project.md docs/context_log.md docs/dev_log.md

# Create script placeholders
mkdir -p scripts
touch scripts/test.sh scripts/e2e.sh

# Generate a default project-spec.json
cat < project-spec.json
{
  "project_name": "New Project",
  "source_dir": "src",
  "docs": {
    "project": "docs/project.md",
    "context_log": "docs/context_log.md",
    "dev_log": "docs/dev_log.md"
  },
  "commands": {
    "static_check": "echo 'lint command not set'",
    "unit_test": "echo 'test command not set'"
  }
}
EOL

echo "Project initialized successfully!"

Golden Rules for AI Agents

These fundamental rules guide the AI agent's behavior, ensuring quality, efficiency, and robustness throughout the development process. Adherence to these principles is crucial for effective and reliable software creation.

Test-now Mandate: After *every* code change, run automated tests and a minimal end-to-end (E2E) smoke. No exceptions.
One Clarification Max: If critical information is missing, ask **one** concise question. Otherwise, choose sensible defaults, record assumptions in `context_log.md`, and proceed.
No Infinite Loops: Each quality gate allows at most **2 retries**. If still failing, log findings, open a blocker, and stop.
Everything Logged: Update `dev_log.md` on every task. Update `context_log.md` when goals, decisions, or constraints change.
Minimal Diffs: Prefer small, isolated changes and patches. Show diffs before commit.

Standard Repository Layout

A consistent repository structure helps the AI agent navigate and manage project files efficiently. This standardized layout promotes clarity and predictability across different projects.

/docs
  project.md       # Overview, goals, requirements, design, test strategy
  context_log.md   # Current goals, decisions, constraints, tasks, assumptions
  dev_log.md       # Chronological task log
/adr              # Architecture Decision Records (ADR-0001.md, ...)
/templates        # TASK.md and other templates
/src              # Source code
/test             # Unit/integration tests
/e2e              # End-to-end smoke/specs
/scripts          # test.sh, e2e.sh, lint/typecheck wrappers
/tmp              # Scratch outputs (not committed)

Rules: Agents write only in `/docs`, `/src`, `/test`, `/e2e`, `/scripts`, `/tmp` unless told otherwise. Never overwrite large files blindly—prefer **PATCH** with smallest diffs. If a required doc/script is missing, **create from templates**.

Definition of Done (Per Task)

A clear "Definition of Done" ensures that every task is completed to a high standard, with all necessary tests passed and documentation updated before finalization.

All three gates pass locally (**static**, **unit/integration**, **E2E**).
Acceptance criteria satisfied and verified in **E2E smoke**.
`dev_log.md` updated; assumptions recorded in `context_log.md`.
Commit message prepared; diffs reviewed for **secrets** & **dead code**.
No unaddressed **high-severity static findings**.

Failure & Escalation Protocol

When tests fail repeatedly, a defined escalation protocol ensures that the issue is properly addressed, preventing infinite loops and providing clear guidance for resolution.

If a gate still fails after **2 retries**:

**Revert** the last change to restore green state (or isolate failing patch).
Append a **Blocker** entry in `context_log.md` with:
- Error message(s) and logs
- Current hypothesis
- Next best step
Stop and request guidance (**include logs and diffs**).

Task Scoping Matrix

This matrix helps to match the effort and required steps to the complexity of the change, optimizing the development process for various task types.

Change Level	Examples	Required Steps
Patch	Bug fix, typo	Test → Code → Verify → Log
Feature	New API endpoint	Plan → Test → Code → Log
Refactor	Architecture change	Plan → ADR → Test → Code

First-Run Checklist

For the initial setup of a new project, this checklist ensures all foundational elements are in place for the AI agent to begin its work effectively.

Create `/docs/project.md`, `/docs/context_log.md`, `/docs/dev_log.md` from templates.
Add **ADR-0001** for stack selection (language/framework, testing libs).
Create `/scripts/test.sh` and `/scripts/e2e.sh` and make them executable.
Seed an initial **E2E smoke** (e.g., `GET /health` route or `cli.py --help`).

Configuration Explorer

The `project-spec.json` file is the brain of the framework, telling the AI agent where to find files and what commands to run. Hover over the keys in the JSON below to understand the role of each configuration.