# Implementation Tasks

**Project**: three-stars
**Last Updated**: 2026-02-21
**Status**: Sprint 6 - DX Review P0/P1 Fixes

## Task Status Legend

| Icon | Status | Meaning |
|------|--------|---------|
| ⬜ | TODO | Not started, available for work |
| 🔄 | IN PROGRESS | Currently being worked on |
| ✅ | DONE | Completed |
| 🚫 | BLOCKED | Waiting on dependency |
| ⏸️ | ON HOLD | Paused |

## Key Principles

- Work in vertical slices (end-to-end features)
- Verify unknowns in `.sandbox/` before production implementation
- Create proposals before changing spec files
- Keep tasks small and independently testable

## Sprint 0: Foundation & Setup

**Goal**: Working Python package with CLI skeleton and test infrastructure
**Deliverable**: `pip install -e .` works, `three-stars --help` shows commands

### Tasks

- ✅ T01: Create `pyproject.toml` with dependencies (click, rich, boto3, pyyaml, hatchling)
- ✅ T02: Create `src/three_stars/__init__.py` and package directory structure
- ✅ T03: Implement `cli.py` with Click command group (deploy/destroy/status/init stubs)
- ✅ T04: Implement `config.py` — YAML loading, validation, ProjectConfig dataclass
- ✅ T05: Set up `tests/` with pytest, conftest.py, and config tests
- ✅ T06: Set up linting (ruff) and formatting in pyproject.toml

## Sprint 1: AWS Core Modules

**Goal**: Individual AWS operations working and tested
**Deliverable**: Each AWS module can create/delete its resource independently

### Tasks

- ✅ T07: Implement `aws/session.py` — boto3 session creation, account ID lookup
- ✅ T08: Implement `aws/s3.py` — bucket CRUD, directory upload with MIME types
- ✅ T09: Implement `aws/cloudfront.py` — distribution CRUD with OAC
- ✅ T10: Implement `aws/cf_function.py` — CloudFront Function CRUD with JS router template
- ✅ T11: Implement `aws/agentcore.py` — Runtime CRUD (adapted from toolkit patterns)
- ✅ T12: Write unit tests with moto mocks for S3/CloudFront; mock boto3 for AgentCore

## Sprint 2: Orchestration

**Goal**: Full deploy/destroy/status workflows working end-to-end
**Deliverable**: `three-stars deploy` creates all resources; `destroy` removes them

### Tasks

- ✅ T13: Implement `deploy.py` — orchestrate all AWS modules with Rich progress display
- ✅ T14: Implement `destroy.py` — reverse teardown with confirmation prompt
- ✅ T15: Implement `status.py` — query resource states, display Rich table
- ✅ T16: Wire orchestrators into CLI commands (connect deploy.py/destroy.py/status.py to cli.py)
- ✅ T17: Implement state file read/write (`.three-stars-state.json`)

## Sprint 3: Init Command & Polish

**Goal**: Complete CLI with init command, error handling, and polished UX
**Deliverable**: Full user workflow from init to destroy works

### Tasks

- ✅ T18: Create `templates/starter/` with minimal project template (config, frontend, agent)
- ✅ T19: Implement `init` command — copy template, substitute project name
- ✅ T20: Add comprehensive error handling (missing credentials, invalid config, permission errors)
- ✅ T21: Add `--yes`, `--region`, `--profile` CLI flag support
- ✅ T22: Integration tests for CLI commands (end-to-end with moto)

## Sprint 4: Documentation & Release

**Goal**: Ready to publish and use
**Deliverable**: Documented, tested, installable package

### Tasks

- ✅ T23: Update README.md with installation, quick start, configuration reference
- ✅ T24: Update spec files with final implementation details
- ✅ T25: Add GitHub Actions CI workflow (lint, test, build)

## Sprint 4.5: DX Improvements

**Goal**: Address developer experience gaps — resource tagging, agent code updates, deployment progress, rollback support
**Deliverable**: Tags on all resources, agent code updates on redeploy, step-numbered progress with health check, --force/--verbose flags, state backup
**Proposal**: `spec/proposals/20260221_dx_review_module_redesign.md`

### Tasks

- ✅ T40: Add `tags` field to `ProjectConfig`, parse from `three-stars.yml`, add `get_resource_tags()` and `tags_to_aws()` helpers
- ✅ T41: Add `backup_state()` to `state.py` — copies state file to `.json.bak` before deploys
- ✅ T42: Add `update_agent_runtime()` to `aws/agentcore.py` — re-packages and updates agent code on existing runtime
- ✅ T43: Add `tag_bucket()` to `aws/s3.py` — applies tags via `put_bucket_tagging()`
- ✅ T44: Add `tags` parameter to all Lambda/IAM role creation in `aws/lambda_bridge.py`
- ✅ T45: Add `tags` parameter to CloudFront distribution creation in `aws/cloudfront.py`
- ✅ T46: Rewrite `deploy.py` — update-in-place for AgentCore, tags on all resources, step-numbered progress with elapsed time, state backup before deploy, post-deployment health check
- ✅ T47: Add `--force` and `--verbose` flags to CLI `deploy` command, add recovery guidance on failure
- ✅ T48: Update `spec/tasks.md` and `spec/design.md` to reflect DX improvements

## Sprint 5: Module Structure Redesign

**Goal**: Reorganize from service-based `aws/` modules to resource-based `resources/` modules with typed state
**Deliverable**: Same CLI behavior, but with typed `DeploymentState`, resource modules with `deploy()`/`destroy()`/`get_status()`, and explicit orchestrator data flow
**Proposal**: `spec/proposals/20260221_redesign_module_structure.md`

### Tasks

- ✅ T26: Rewrite `state.py` — Define typed state dataclasses (`DeploymentState`, `AgentCoreState`, `StorageState`, `ApiBridgeState`, `EdgeState`, `CdnState`). Update `load_state()`/`save_state()` for dataclass serialization via `dataclasses.asdict()`.
- ✅ T27: Create `naming.py` — Extract resource name computation from `deploy.py` into `ResourceNames` frozen dataclass with `compute_names()` function.
- ✅ T28: Create `resources/` package — `__init__.py` with `ResourceStatus` namedtuple; `_base.py` with shared helpers (session creation re-export, progress utils).
- ✅ T29: Create `resources/agentcore.py` — Move IAM role + runtime + endpoint logic from `aws/agentcore.py`. Expose `deploy() -> AgentCoreState`, `destroy(AgentCoreState)`, `get_status(AgentCoreState)`.
- ✅ T30: Create `resources/storage.py` — Move S3 bucket + upload logic from `aws/s3.py`. Expose `deploy() -> StorageState`, `destroy(StorageState)`, `get_status(StorageState)`.
- ✅ T31: Create `resources/api_bridge.py` — Move Lambda bridge logic from `aws/lambda_bridge.py` (non-edge). Expose `deploy(*, agent_runtime_arn: str) -> ApiBridgeState`, `destroy(ApiBridgeState)`, `get_status(ApiBridgeState)`.
- ✅ T32: Create `resources/edge.py` — Move Lambda@Edge logic from `aws/lambda_bridge.py`. Expose `deploy() -> EdgeState`, `destroy(EdgeState)`, `get_status(EdgeState)`.
- ✅ T33: Create `resources/cdn.py` — Move CloudFront logic from `aws/cloudfront.py`. Expose `deploy(*, bucket_name, lambda_function_url, lambda_function_name, edge_function_arn) -> CdnState`, `destroy(CdnState)`, `get_status(CdnState)`.
- ✅ T34: Rewrite `deploy.py` — Step-by-step orchestration using typed state assignment (`state.agentcore = agentcore.deploy(...)`) with cross-resource data threading via typed attribute access.
- ✅ T35: Rewrite `destroy.py` — Reverse-order teardown, each module receives its own typed state. `None` check for partially-deployed stacks.
- ✅ T36: Rewrite `status.py` — Each module's `get_status()` receives its own typed state.
- ✅ T37: Migrate tests from `tests/aws/` to `tests/resources/`. Update imports and state assertions to use typed dataclasses.
- ✅ T38: Delete `aws/` directory (including unused `cf_function.py`).
- ✅ T39: Run full test suite and linter — verify zero regressions, `ruff check` and `ruff format` pass.

## Sprint 5.5: Remove `src/` Directory Nesting

**Goal**: Flatten package layout by removing the `src/` wrapper directory
**Deliverable**: `three_stars/` package lives at project root instead of `src/three_stars/`
**Proposal**: `spec/proposals/20260221_dx_review_module_redesign.md` (DX improvements — approved)

### Tasks

- ✅ T50: Move `src/three_stars/` to `three_stars/` at project root — remove `src/` directory
- ✅ T51: Update `pyproject.toml` — change `[tool.hatch.build.targets.wheel]` packages, `[tool.ruff]` src, and `[tool.pytest.ini_options]` pythonpath for flat layout
- ✅ T52: Update all spec files and proposals to reference `three_stars/` instead of `src/three_stars/`
- ✅ T53: Verify `pip install -e .`, tests, and linter work with flat layout

## Sprint 6: DX Review P0/P1 Fixes

**Goal**: Fix critical documentation-implementation mismatches and improve first-run experience
**Deliverable**: README matches actual CLI, architecture docs are accurate, agent template supports local testing
**Proposal**: `spec/proposals/20260221_apply_dx_review_p0_p1_fixes.md`

### Tasks

- ✅ T54: Add `three-stars` as secondary entry point in `pyproject.toml` alongside `sss`
- ✅ T55: Rewrite README.md — fix CLI name (`sss`), Python version (3.12+), architecture (Lambda not CloudFront Functions), deploy output (5-step), add `--force`/`--verbose` flags, update dev section to use `uv`
- ✅ T56: Update architecture diagram — replace CloudFront Functions with Lambda API Bridge + Lambda@Edge
- ✅ T57: Add `if __name__ == "__main__"` local testing block to `templates/starter/agent/agent.py`
- ✅ T58: Update `spec/requirements.md` — fix CloudFront Function refs to Lambda, fix Python 3.11+ to 3.12+, fix CLI name in user stories
- ✅ T59: Update `spec/design.md` — fix CLI entry point reference, fix deploy sequence order
- ✅ T60: Run full test suite and linter — verify zero regressions

## Backlog

Items not yet scheduled:

- ⬜ Custom domain name support (ACM + Route53)
- ⬜ Multiple environment support (dev/staging/prod)
- ⬜ Streaming agent responses (SSE/WebSocket)
- ⬜ Cost estimation command
- ⬜ `three-stars logs` command for agent logs

## Reference

### Project Structure

```
three-stars/
├── pyproject.toml
├── three_stars/              # Package at project root (flat layout)
│   ├── __init__.py
│   ├── cli.py
│   ├── config.py
│   ├── state.py             # Typed DeploymentState + per-resource state dataclasses
│   ├── naming.py            # ResourceNames frozen dataclass
│   ├── deploy.py            # Orchestrator with typed state
│   ├── destroy.py           # Reverse-order with typed per-module state
│   ├── status.py            # Status with typed per-module state
│   ├── init.py
│   └── resources/           # Resource modules (replaces aws/)
│       ├── __init__.py
│       ├── _base.py
│       ├── agentcore.py
│       ├── storage.py
│       ├── api_bridge.py
│       ├── edge.py
│       └── cdn.py
├── tests/
│   ├── conftest.py
│   ├── test_cli.py
│   ├── test_config.py
│   ├── test_deploy.py
│   └── resources/
│       ├── test_agentcore.py
│       ├── test_storage.py
│       ├── test_api_bridge.py
│       ├── test_edge.py
│       └── test_cdn.py
├── templates/
│   └── starter/
│       ├── three-stars.yml
│       ├── app/
│       │   └── index.html
│       └── agent/
│           ├── requirements.txt
│           └── agent.py
└── spec/
```

### Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| click | >=8.1 | CLI framework |
| rich | >=13.0 | Terminal UX |
| boto3 | >=1.35 | AWS SDK |
| pyyaml | >=6.0 | Config parsing |
| pytest | >=8.0 | Testing (dev) |
| moto | >=5.0 | AWS mocks (dev) |
| ruff | >=0.9 | Linting (dev) |
