Autonomous SDLC platform — from GitHub issue to merged, reviewed code.
Telos orchestrates Claude Code AI agents on AWS to plan, implement, review, and ship software end-to-end. Label a GitHub issue kickoff, and Telos autonomously generates an architecture document, decomposes the work into a dependency-aware task graph, implements each task as a pull request, runs an AI code review cycle, and merges PRs in topological order — with no human intervention required on the happy path.
Telos wrote itself. Of the 26 commits in this repository, exactly one is mine — Initial commit, an empty scaffold on 2026-02-26. The other 25 were authored by autonomous dev-agents over the following three days: architecture docs, the task graph, every Lambda handler, the CDK stack, the worker modes, and the test suite.
Those agents belong to a separate autonomous-SDLC platform I built. Telos is its clean-room successor — a second pass at the same idea, designed to collapse a fleet of custom orchestration services into a single Step Functions state machine and one TASK_TYPE-routed container image.
TASK.md at the repository root is a leftover artifact of that process: the literal work order handed to a dev-agent for a PR revision cycle, including the reviewer agent's requested changes. It was never cleaned up, and it is more honest left in place.
GitHub Issue (label: "kickoff")
│
▼
API Gateway → Webhook Lambda → SQS FIFO
│
▼ (EventBridge Pipe)
Step Functions State Machine
├─ bootstrap-project → create project record in DynamoDB
├─ bootstrap-repo → create GitHub repo, set branch protection
├─ generate-architecture → ECS architect agent → HLD/architecture docs
├─ plan-tasks → ECS planner agent → task graph + GitHub issues
├─ trigger-task → ECS developer agent → branch + code + PR
├─ review-pr → ECS reviewer agent → review comments
│ ├─ APPROVE → merge-pr → close issue → next task
│ └─ REQUEST_CHANGES → revise-pr → re-review loop
└─ update-status → mark project COMPLETED
Every step produces a durable artifact: architecture documents committed to the repository, GitHub issues for each task, pull requests with AI-generated review comments, and execution records in DynamoDB. The full workflow history is auditable via Step Functions, CloudWatch, and git commit history.
Ad-hoc tasks: Comment /work on any GitHub issue to trigger a single-task flow (implement → review → merge) without bootstrapping a full project.
Telos is built on five AWS primitives wired together with zero custom glue services:
| Layer | Service | Role |
|---|---|---|
| Ingress | API Gateway HTTP API | GitHub webhook receiver |
| Queue | SQS FIFO + DLQ | Ordered, exactly-once work delivery |
| Orchestration | AWS Step Functions (Standard) | Workflow state machine with retry/backoff |
| Compute (light) | AWS Lambda (Node.js 22) | 16 handler functions |
| Compute (heavy) | Amazon ECS Fargate (ARM64) | 6 Claude Code agent task types |
| Data | Amazon DynamoDB (on-demand) | 5 tables: projects, task-graphs, runs, task-outputs, repo-locks |
| Secrets | AWS Secrets Manager + SSM Parameter Store | GitHub App key, Claude OAuth token (Secrets Manager); webhook HMAC secret (SSM SecureString) |
| Networking | VPC, private subnets, NAT Gateway, VPC endpoints | No public ingress to compute |
| Observability | CloudWatch Logs, Alarms, Dashboards | Structured JSON logging + alerting |
For detailed component specifications, see docs/HLD.md. For data models, API specs, and deployment strategy, see docs/ARCHITECTURE.md. For SOC 2 compliance guidance, see docs/SOC2.md.
| Category | Technology |
|---|---|
| Language | TypeScript 5.x (strict, ESM-only) |
| Runtime | Node.js 22 (Active LTS) |
| Package manager | pnpm workspaces |
| Linter / Formatter | Biome |
| Test framework | Vitest |
| Schema validation | Zod |
| Infrastructure | AWS CDK v2 |
| GitHub SDK | Octokit |
| AI agent | Claude Code CLI (headless, --print mode) |
telos/
├── packages/
│ ├── core/ # @telos/core — shared library
│ │ # config, DynamoDB services, GitHub connector,
│ │ # logger, merge policy, system prompts
│ ├── worker/ # ECS Fargate worker (6 modes: architect, planner,
│ │ # developer, reviewer, reviser, rebaser)
│ ├── lambdas/ # 16 Lambda handler functions
│ └── cdk/ # AWS CDK infrastructure-as-code
│
├── docs/
│ ├── HLD.md # High-Level Design document
│ ├── ARCHITECTURE.md # Architecture, data models, API specs
│ └── SOC2.md # SOC 2 compliance guide
│
├── bootstrap.sh # Idempotent dev environment setup
├── biome.json # Linter/formatter config
├── vitest.workspace.ts # Test workspace (4 workspaces)
└── pnpm-workspace.yaml # Monorepo workspace definition
| Tool | Version | Install |
|---|---|---|
| Node.js | 22.x (Active LTS) | nodejs.org or nvm use |
| pnpm | latest | corepack enable && corepack prepare pnpm@latest --activate |
| AWS CDK CLI | latest | npm install -g aws-cdk |
| Docker | latest | Docker Desktop |
| AWS CLI | v2 | aws.amazon.com/cli |
| AWS account | — | With permissions to deploy CDK stacks |
An .nvmrc file pins the Node.js version. Run nvm use to activate it automatically.
# Clone the repository
git clone https://github.com/tdrml/telos.git
cd telos
# Run the idempotent setup script
# Checks prerequisites, installs dependencies, builds, type-checks, and runs tests
./bootstrap.shAfter setup, configure the required secrets in AWS Secrets Manager:
| Secret name | Contents |
|---|---|
telos/{env}/github-app |
GitHub App private key JSON |
telos/{env}/claude-oauth |
Claude Code CLI OAuth token |
Store the webhook HMAC secret in AWS Systems Manager Parameter Store as a SecureString:
| Parameter name | Type | Contents |
|---|---|---|
telos/{env}/webhook-secret |
SecureString |
HMAC secret for webhook signature validation |
Then bootstrap and deploy the CDK stack:
cd packages/cdk
cdk bootstrap aws://<ACCOUNT_ID>/<REGION>
cdk deploy --context env=devRun these from the monorepo root:
# Install dependencies (deterministic, frozen lockfile)
pnpm install --frozen-lockfile
# Build all packages (core first, then others in parallel)
pnpm build
# Run all tests across all workspaces
pnpm test
# Lint and format check
pnpm lint
# Remove build output
pnpm clean
# Deploy infrastructure to AWS
cd packages/cdk && cdk deploy --context env=devNote:
pnpm lintcurrently reports 17 style findings inpackages/cdk/(useImportType,noEmptyInterface,useLiteralKeys). They are cosmetic and pre-existing — the test suite is green at 732/732.
| Document | Description |
|---|---|
| docs/OVERVIEW.md | Start here — end-to-end system overview, data flow diagram, use cases, design principles |
| docs/HLD.md | High-Level Design: component responsibilities, data flow, Lambda catalog |
| docs/ARCHITECTURE.md | Technology choices, data models, API specs, deployment strategy |
| docs/SOC2.md | SOC 2 compliance guide for operators |
MIT — see LICENSE.