worclaude 1.0.0

package/templates/skills/universal/subagent-usage.md

@@ -0,0 +1,108 @@
+---
+description: "When to use subagents, how many, context hygiene, worktree isolation patterns"
+---
+
+# Subagent Usage
+
+## What Subagents Are
+
+Subagents are separate Claude instances spawned from your main session. They have
+their own context window, execute independently, and return results to the main
+session. Your main context stays clean.
+
+## When Subagents Help
+
+Tasks that benefit from subagents:
+- **Testing**: writing tests for code you just implemented (test-writer agent)
+- **Code review**: reviewing your own changes for quality (code-simplifier agent)
+- **Research**: reading many files to answer a specific question
+- **Parallel work**: running verification while you continue designing
+- **Build validation**: checking that everything compiles and passes (build-validator)
+- **File generation**: creating boilerplate, configs, or template files
+
+The common thread: these tasks require context (reading files, understanding code)
+but that context doesn't need to persist in your main session.
+
+## When NOT to Use Subagents
+
+- Tasks requiring back-and-forth with the user (subagents can't interact with users)
+- Tasks where the result needs deep integration with your current reasoning
+- Very small tasks (the overhead of spawning isn't worth it)
+- Tasks that depend on conversation history the subagent doesn't have
+
+## Context Hygiene
+
+Your main session has limited context. Every file you read, every long output you
+generate, consumes context. Subagents let you offload this:
+
+Instead of:
+1. Read 10 test files to understand patterns (consumes context)
+2. Write new tests (uses that context)
+3. Continue main work (context is now polluted with test details)
+
+Do:
+1. Spawn test-writer subagent with: "write tests for src/merger.js following
+   patterns in tests/core/"
+2. Continue main work while subagent works
+3. Subagent returns: "wrote 3 test files, all passing"
+4. Main context stays clean
+
+## Parallel vs Sequential Subagents
+
+**Parallel**: when tasks are independent.
+- Run test-writer and code-simplifier on different parts of the code simultaneously
+- Run build-validator while continuing implementation
+
+**Sequential**: when tasks depend on each other.
+- Run code-simplifier first, then test-writer on the simplified code
+- Run security-reviewer first, then fix the issues it found
+
+Don't spawn more than 2-3 parallel subagents. Each consumes resources and
+coordination overhead grows.
+
+## Worktree Isolation
+
+Some agents use `git worktree` to make changes without affecting your working tree:
+
+How it works:
+1. Agent creates a worktree from your current branch
+2. Makes changes in the worktree (isolated from your files)
+3. Commits changes
+4. You merge or cherry-pick the results
+
+Agents with worktree isolation: code-simplifier, test-writer, verify-app, ci-fixer,
+bug-fixer, refactorer, doc-writer.
+
+Benefits:
+- Agent's changes don't conflict with your uncommitted work
+- You can review agent changes before merging
+- If the agent breaks something, it's isolated
+
+## Giving Subagents Good Instructions
+
+Subagents start with zero context. They don't know what you've been doing. Give them:
+
+1. **The specific task**: "Write unit tests for the merge function in src/core/merger.js"
+2. **Where to look**: "Follow patterns from tests/core/detector.test.js"
+3. **Constraints**: "Use Vitest, not Jest. Mock fs-extra, not the actual filesystem."
+4. **Success criteria**: "All tests should pass. Cover happy path, error cases,
+   and the three-way merge edge case."
+
+Bad instruction: "Write some tests"
+Good instruction: "Write unit tests for detectScenario() in src/core/detector.js.
+Test all three scenarios: fresh (no .claude/), existing (.claude/ but no meta),
+upgrade (meta exists). Mock the filesystem. Use Vitest."
+
+## Gotchas
+
+- Subagents don't see your uncommitted changes unless they share the same working
+  directory. If you need them to see your changes, commit first or use the same
+  worktree.
+- Subagent output is returned to your context. If a subagent generates a huge report,
+  that report consumes your context. Ask for concise results.
+- Don't use subagents for tasks that require judgment about the overall session
+  direction. They lack the conversational context to make those calls.
+- Worktree-based agents need a clean git state to create the worktree. Commit or
+  stash before spawning them.
+- If a subagent fails, don't automatically retry. Understand why it failed first.
+  The same instructions will produce the same failure.

package/templates/skills/universal/testing.md

@@ -0,0 +1,116 @@
+---
+description: "Test philosophy, coverage strategy, test-first patterns, what to test and what not to"
+---
+
+# Testing
+
+## What to Test
+
+Test behavior, not implementation. A test should verify what a function does, not
+how it does it. If you refactor the internals and the test breaks, the test was
+testing the wrong thing.
+
+Good test: "given a valid email, returns true"
+Bad test: "calls regex.match with pattern /^[a-z].../"
+
+## Meaningful Coverage vs Line Coverage
+
+100% line coverage is a vanity metric. You can have 100% coverage and still ship bugs
+if your tests don't exercise meaningful paths.
+
+Focus coverage on:
+- Business logic (the rules that make your app unique)
+- Error handling paths (what happens when things go wrong)
+- Boundary conditions (empty, null, max values, off-by-one)
+- Integration points (where your code meets external systems)
+
+Skip coverage on:
+- Simple getters/setters
+- Framework boilerplate
+- Generated code
+- Pure delegation (functions that just call another function)
+
+## Edge Cases Worth Testing
+
+Every function has these potential edge cases. Consider which apply:
+
+- Null / undefined / empty string
+- Empty array / empty object
+- Single element
+- Very large input
+- Negative numbers / zero
+- Unicode and special characters
+- Concurrent access
+- Network timeout / failure
+
+You don't need to test ALL of these for every function. Think about which ones
+are realistic for your specific case.
+
+## Test-First Workflow
+
+Writing tests first helps when:
+- The behavior is well-defined but the implementation isn't clear
+- You're fixing a bug (write the failing test first, then fix)
+- You're implementing a spec (tests become the spec's executable form)
+
+Test-first hurts when:
+- You're exploring and don't know what the API should look like
+- You're prototyping and will throw the code away
+- The test would be trivial (testing that a constant equals itself)
+
+When doing test-first: write the test, watch it fail, implement the minimum to pass,
+then refactor. Don't write all the tests up front — go one at a time.
+
+## Test Structure
+
+Follow Arrange-Act-Assert (AAA):
+
+```
+// Arrange: set up the test conditions
+const input = createValidInput();
+
+// Act: call the thing being tested
+const result = processInput(input);
+
+// Assert: verify the outcome
+expect(result.status).toBe('success');
+```
+
+Keep tests independent. No test should depend on another test running first.
+No shared mutable state between tests.
+
+## Naming Tests
+
+Test names should read like specifications:
+- "should return 401 when token is expired"
+- "should merge arrays without duplicates"
+- "should create backup directory if it doesn't exist"
+
+Not:
+- "test1"
+- "it works"
+- "handles edge case"
+
+## Testing Anti-Patterns
+
+- **Snapshot abuse**: snapshots test that output didn't change, not that it's correct.
+  Use sparingly and review snapshot diffs carefully.
+- **Mock everything**: if your test mocks 5 dependencies, you're testing the mocking
+  framework, not your code. Prefer integration tests for heavily-connected code.
+- **Test the framework**: don't test that Express routes requests or that React renders
+  components. Trust the framework; test YOUR logic.
+- **Brittle assertions**: asserting on exact error messages or full object shapes when
+  only one field matters. Assert on what matters.
+- **Slow tests without reason**: if a test takes seconds, it's probably doing I/O
+  that should be mocked or it's an integration test that should be tagged separately.
+
+## Gotchas
+
+- Flaky tests are worse than no tests. They erode trust in the entire suite.
+  Fix immediately or quarantine with a clear TODO.
+- Test data should be self-contained. Don't rely on database state, external
+  services, or file system artifacts from other tests.
+- When a test fails, the test might be wrong. Don't assume the code is broken —
+  read the test carefully first.
+- Delete tests that test deleted features. Orphan tests confuse and mislead.
+- Async tests need proper awaiting. An unawaited assertion silently passes.

package/templates/skills/universal/verification.md

@@ -0,0 +1,120 @@
+---
+description: "Domain-specific verification beyond tests, closing the feedback loop for web, API, CLI, data"
+---
+
+# Verification
+
+## Beyond Unit Tests
+
+Unit tests verify code logic. Verification confirms the feature actually works in
+its real environment. Both are necessary. Neither alone is sufficient.
+
+The /verify command runs automated checks, but domain-specific verification often
+requires manual steps or specialized tooling.
+
+## Closing the Feedback Loop
+
+Every change needs a feedback loop: make a change, verify it worked, then move on.
+The loop must be closed BEFORE committing.
+
+Bad workflow: change code -> commit -> move to next task -> discover it's broken
+Good workflow: change code -> verify -> commit -> move to next task
+
+## Web Application Verification
+
+After changing UI or API behavior:
+
+1. Start the dev server
+2. Navigate to the affected page/endpoint
+3. Test the happy path manually
+4. Test at least one error path
+5. Check browser console for errors/warnings
+6. Verify responsive behavior if UI changed
+
+For API changes:
+```bash
+# Test the endpoint directly
+curl -X POST http://localhost:3000/api/resource \
+  -H "Content-Type: application/json" \
+  -d '{"field": "value"}'
+
+# Check response status and body
+```
+
+## API Verification
+
+Test beyond the happy path:
+- Valid request with all fields
+- Valid request with minimum fields
+- Invalid request (missing required field)
+- Invalid request (wrong types)
+- Authentication failures
+- Rate limiting behavior
+- Concurrent request handling (if relevant)
+
+Use curl, httpie, or the project's API test suite. Automate what you can, but
+do at least one manual check of the actual running server.
+
+## CLI Verification
+
+After changing CLI behavior:
+
+1. Run the command with typical arguments
+2. Run with edge case arguments (empty, very long, special characters)
+3. Run with invalid arguments (verify error messages are helpful)
+4. Test piping and redirection if applicable
+5. Verify exit codes
+
+```bash
+# Test normal usage
+my-cli init --name "test project"
+
+# Test error handling
+my-cli init  # missing required flag
+
+# Test edge cases
+my-cli init --name ""  # empty string
+```
+
+## Data Pipeline Verification
+
+After changing data transformations:
+
+1. Run with sample input data
+2. Verify output schema matches expectations
+3. Check row counts (input vs output)
+4. Spot-check specific records for correctness
+5. Test with empty input
+6. Test with malformed input
+
+## Build Verification
+
+The full verification suite (triggered by /verify):
+
+1. `npm test` / `pytest` / `cargo test` — unit and integration tests
+2. `npm run build` / equivalent — compilation and bundling
+3. `npm run lint` / equivalent — style and static analysis
+4. Type checking if applicable (`tsc --noEmit`, `mypy`, etc.)
+5. Domain-specific checks from above
+
+All five must pass. If any fails, stop and fix before continuing.
+
+## When Verification Reveals Problems
+
+If verification fails:
+1. Don't panic. Read the error carefully.
+2. Check if it's a pre-existing issue or something you introduced.
+3. If you introduced it, fix it before committing.
+4. If it's pre-existing, document it and decide whether to fix now or file it.
+
+## Gotchas
+
+- "Tests pass" is not the same as "it works." A test suite can have 100% coverage
+  and still miss real-world failures. Always do at least one real verification.
+- Don't skip verification because "it's a small change." Small changes cause
+  production outages too.
+- Browser console errors are free bug reports. Check them.
+- If verification is painful, invest in making it easier. A script that starts
+  the server, runs checks, and reports results saves cumulative hours.
+- Flaky tests must be fixed or quarantined. A test suite that sometimes fails
+  trains people to ignore failures.

package/templates/spec-md-backend.md

@@ -0,0 +1,85 @@
+# SPEC.md — {project_name}
+
+## Product Overview
+{description}
+
+## Tech Stack
+| Layer       | Technology                        |
+|-------------|-----------------------------------|
+| Language    | {tech_stack_table}                |{docker_row}
+| Framework   | [e.g. Express, FastAPI, Gin]      |
+| Database    | [e.g. PostgreSQL, MongoDB, Redis] |
+| Auth        | [e.g. JWT, API keys, OAuth2]      |
+| Hosting     | [e.g. AWS, Railway, Fly.io]       |
+| CI/CD       | [e.g. GitHub Actions]             |
+
+## API Endpoints
+| Method | Path                  | Purpose                          | Auth Required |
+|--------|-----------------------|----------------------------------|---------------|
+| POST   | `/api/auth/login`     | [Authenticate and return token]  | No            |
+| POST   | `/api/auth/register`  | [Create new user account]        | No            |
+| GET    | `/api/[resource]`     | [List with pagination/filtering] | [Yes/No]      |
+| GET    | `/api/[resource]/:id` | [Get single resource by ID]      | [Yes/No]      |
+| POST   | `/api/[resource]`     | [Create new resource]            | [Yes/No]      |
+| PUT    | `/api/[resource]/:id` | [Full update of resource]        | [Yes/No]      |
+| PATCH  | `/api/[resource]/:id` | [Partial update of resource]     | [Yes/No]      |
+| DELETE | `/api/[resource]/:id` | [Soft/hard delete resource]      | [Yes/No]      |
+
+## Data Model
+### [PrimaryEntity]
+| Field       | Type      | Constraints                      |
+|-------------|-----------|----------------------------------|
+| id          | UUID      | Primary key, auto-generated      |
+| [field]     | [type]    | [required, unique, indexed, etc] |
+| created_at  | Timestamp | Auto-set on creation             |
+| updated_at  | Timestamp | Auto-set on update               |
+
+### [SecondaryEntity]
+| Field       | Type      | Constraints                      |
+|-------------|-----------|----------------------------------|
+| id          | UUID      | Primary key, auto-generated      |
+| [field]     | [type]    | [constraints]                    |
+| [foreign]   | UUID      | FK -> [PrimaryEntity].id         |
+
+## Authentication & Authorization
+- **Strategy:** [JWT bearer tokens / API key header / OAuth2]
+- **Roles:** [e.g. admin, user, service — describe permissions per role]
+- **Token lifetime:** [e.g. 15m access, 7d refresh]
+- **Rate limiting:** [e.g. 100 req/min per API key]
+
+## Error Handling
+Response format: `{ "error": { "code": "MACHINE_CODE", "message": "...", "details": "..." } }`
+
+| HTTP Status | When Used                                |
+|-------------|------------------------------------------|
+| 400         | Validation failure, malformed request    |
+| 401         | Missing or invalid authentication        |
+| 403         | Authenticated but not authorized         |
+| 404         | Resource not found                       |
+| 409         | Conflict (duplicate, stale update)       |
+| 422         | Business logic violation                 |
+| 429         | Rate limit exceeded                      |
+| 500         | Unhandled server error                   |
+
+## Implementation Phases
+
+### Phase 1 — Foundation
+- [ ] Project scaffolding and dependency setup
+- [ ] Database connection and schema migrations
+- [ ] Basic CRUD for [primary resource]
+- [ ] Authentication (signup, login, token refresh)
+- [ ] Request validation middleware
+
+### Phase 2 — Core Features
+- [ ] Remaining resource endpoints
+- [ ] Business logic and domain rules
+- [ ] Pagination, filtering, and sorting
+- [ ] Authorization and role checks
+- [ ] Background jobs [if applicable]
+
+### Phase 3 — Polish
+- [ ] Rate limiting, input sanitization, security hardening
+- [ ] OpenAPI / Swagger documentation
+- [ ] Logging, health-check endpoint, comprehensive error handling
+- [ ] Integration and load tests
+- [ ] Deployment pipeline and monitoring

package/templates/spec-md-cli.md

@@ -0,0 +1,79 @@
+# SPEC.md — {project_name}
+
+## Product Overview
+{description}
+
+## Tech Stack
+| Layer        | Technology                        |
+|--------------|-----------------------------------|
+| Language     | {tech_stack_table}                |{docker_row}
+| CLI Framework| [e.g. Commander.js, Click, Cobra] |
+| Output       | [e.g. Chalk, Rich, colored]      |
+| Testing      | [e.g. Vitest, pytest]            |
+| Distribution | [e.g. npm, PyPI, Homebrew]       |
+
+## Commands
+| Command                   | Description                          | Flags / Options                |
+|---------------------------|--------------------------------------|--------------------------------|
+| `{project_name} init`    | [Initialize configuration/project]   | `--template <name>`, `--force` |
+| `{project_name} [verb]`  | [Primary action of the tool]         | `--flag`, `-f <value>`         |
+| `{project_name} [verb]`  | [Secondary action]                   | `--verbose`, `--json`          |
+| `{project_name} config`  | [View/edit configuration]            | `--set <key=value>`, `--list`  |
+| `{project_name} --help`  | Show help text                       | —                              |
+| `{project_name} --version`| Print version                       | —                              |
+| [add commands...]         | [description]                        | [flags]                        |
+
+## Configuration
+**Config file:** `~/.{project_name}rc` or `.{project_name}.json` in project root
+
+**Precedence (highest to lowest):** CLI flags > env vars (`{PROJECT_NAME}_[KEY]`) > project config > user config > defaults
+
+| Variable                     | Purpose                          | Default     |
+|------------------------------|----------------------------------|-------------|
+| `{PROJECT_NAME}_CONFIG`      | [Path to config file]            | [~/.rc]     |
+| `{PROJECT_NAME}_[OPTION]`    | [Override for specific option]   | [default]   |
+
+## Input / Output Formats
+- **stdin:** [Does the tool read from stdin? Pipe support?]
+- **stdout:** [Human-readable by default, machine-readable with `--json`]
+- **stderr:** [Error messages, progress info, warnings]
+- **File I/O:** [Does it read/write files? Which formats?]
+
+Example output:
+```
+[Show a realistic example of the tool's primary output]
+```
+
+## Error Handling
+| Exit Code | Meaning                              |
+|-----------|--------------------------------------|
+| 0         | Success                              |
+| 1         | General error                        |
+| 2         | Invalid usage / bad arguments        |
+| 3         | Configuration error                  |
+| [code]    | [specific error condition]           |
+
+- **Error format:** `Error: [message]` to stderr, non-zero exit code
+- **Verbose mode:** `--verbose` or `-v` for debug output
+- **Graceful shutdown:** Handle SIGINT/SIGTERM for cleanup
+
+## Implementation Phases
+
+### Phase 1 — Foundation
+- [ ] Project scaffolding and CLI argument parsing
+- [ ] Config file loading and validation
+- [ ] Help text and version flag
+- [ ] Basic `init` command
+- [ ] Error handling framework
+
+### Phase 2 — Core Commands
+- [ ] Primary command ([verb]) with full functionality
+- [ ] Secondary commands
+- [ ] stdin/stdout pipe support
+- [ ] `--json` output mode
+
+### Phase 3 — Polish
+- [ ] Interactive prompts, progress indicators, `--no-color` support
+- [ ] Shell completions (bash, zsh, fish)
+- [ ] Tests for all commands and edge cases
+- [ ] Package and publish

package/templates/spec-md-data.md

@@ -0,0 +1,74 @@
+# SPEC.md — {project_name}
+
+## Product Overview
+{description}
+
+## Tech Stack
+| Layer          | Technology                        |
+|----------------|-----------------------------------|
+| Language       | {tech_stack_table}                |{docker_row}
+| ML Framework   | [e.g. PyTorch, scikit-learn, TF]  |
+| Data Storage   | [e.g. S3, BigQuery, PostgreSQL]   |
+| Orchestration  | [e.g. Airflow, Prefect, Dagster]  |
+| Experiment Tracking | [e.g. MLflow, W&B, DVC]     |
+| Serving        | [e.g. FastAPI, BentoML, SageMaker]|
+
+## Data Sources
+| Source            | Format    | Frequency     | Volume         | Notes                |
+|-------------------|-----------|---------------|----------------|----------------------|
+| [Database/API]    | [CSV/JSON]| [Daily/Real-time] | [~N rows/GB] | [Access method]     |
+| [File system]     | [Parquet] | [One-time]    | [~N GB]        | [Schema notes]       |
+| [External API]    | [JSON]    | [Hourly]      | [~N records]   | [Rate limits, auth]  |
+| [add sources...]  | [format]  | [frequency]   | [volume]       | [notes]              |
+
+## Pipeline Architecture
+```
+[Data Source] -> [Ingestion] -> [Raw Storage] -> [Validation & Cleaning]
+  -> [Feature Engineering] -> [Training] / [Analytics]
+  -> [Model Registry] -> [Serving / Inference]
+```
+[Describe each stage: tools used, data transformations, scheduling, failure handling]
+
+## Model Architecture
+[Skip this section if not an ML project]
+- **Task type:** [Classification / Regression / Generation / etc.]
+- **Input features:** [List key features and their types]
+- **Output:** [Prediction format, e.g. class label, score, text]
+- **Baseline model:** [Simple approach to benchmark against]
+- **Target model:** [Architecture description — layers, parameters]
+- **Training data split:** [e.g. 80/10/10 train/val/test]
+- **Hyperparameters:** [Key tunable values and search strategy]
+
+## Evaluation Metrics
+| Metric       | Target   | Baseline | Purpose                          |
+|--------------|----------|----------|----------------------------------|
+| [Accuracy]   | [>0.95]  | [0.82]   | [Primary performance measure]    |
+| [Latency]    | [<100ms] | [—]      | [Inference speed requirement]    |
+| [F1 Score]   | [>0.90]  | [0.75]   | [Balance precision and recall]   |
+| [add more...] | [target]| [current]| [why this metric matters]        |
+
+- **Monitoring:** [How model drift and data quality are tracked in production]
+- **Retraining trigger:** [Schedule-based, drift-based, or manual]
+
+## Implementation Phases
+
+### Phase 1 — Data Foundation
+- [ ] Data source connectors and ingestion scripts
+- [ ] Raw data storage and schema validation
+- [ ] Exploratory data analysis notebook
+- [ ] Data cleaning and preprocessing pipeline
+- [ ] Pipeline orchestration setup
+
+### Phase 2 — Feature Engineering & Modeling
+- [ ] Feature engineering pipeline
+- [ ] Baseline model training and evaluation
+- [ ] Target model experimentation
+- [ ] Hyperparameter tuning
+- [ ] Experiment tracking integration
+
+### Phase 3 — Productionization
+- [ ] Model serialization and registry
+- [ ] Serving API or batch inference pipeline
+- [ ] Monitoring and alerting (data drift, model performance)
+- [ ] Automated retraining pipeline
+- [ ] Documentation and reproducibility checks

package/templates/spec-md-devops.md

@@ -0,0 +1,87 @@
+# SPEC.md — {project_name}
+
+## Product Overview
+{description}
+
+## Infrastructure Stack
+| Layer            | Technology                        |
+|------------------|-----------------------------------|
+| Language         | {tech_stack_table}                |{docker_row}
+| IaC              | [e.g. Terraform, Pulumi, CDK]    |
+| Container Runtime| [e.g. Docker, Podman]            |
+| Orchestration    | [e.g. Kubernetes, ECS, Nomad]    |
+| CI/CD            | [e.g. GitHub Actions, GitLab CI] |
+| Registry         | [e.g. ECR, GHCR, Docker Hub]     |
+| DNS / CDN        | [e.g. Cloudflare, Route53+CF]    |
+| Secrets          | [e.g. Vault, AWS SSM, SOPS]      |
+
+## Environments
+| Name        | URL / Endpoint              | Purpose                    | Access              |
+|-------------|-----------------------------|----------------------------|---------------------|
+| Development | [dev.example.com]           | [Feature testing]          | [Team-wide]         |
+| Staging     | [staging.example.com]       | [Pre-prod validation]      | [Team + QA]         |
+| Production  | [example.com]               | [Live user traffic]        | [Restricted]        |
+| [add env...] | [url]                      | [purpose]                  | [who has access]    |
+
+**Promotion flow:** Development -> Staging -> Production
+[Describe how code and config move between environments — automated, manual gate, etc.]
+
+## CI/CD Pipeline
+```
+[push] -> Lint -> Test -> Build -> [merge to main] -> Deploy Staging -> Smoke Tests
+                                   [tag pushed]    -> Deploy Production -> Smoke Tests -> Post-deploy checks
+```
+| Stage              | Trigger          | Actions                              |
+|--------------------|------------------|--------------------------------------|
+| Lint & Test        | Every push       | [Linter, type check, unit tests]     |
+| Build              | PR to main       | [Docker build, artifact creation]     |
+| Deploy Staging     | Merge to main    | [Auto-deploy, run migrations]        |
+| Deploy Production  | Git tag / manual | [Blue-green or rolling deploy]       |
+| Rollback           | Manual           | [Revert to previous version]         |
+
+## Monitoring & Alerting
+| Signal          | Tool                    | Alert Threshold               |
+|-----------------|-------------------------|-------------------------------|
+| Uptime          | [e.g. UptimeRobot]      | [< 99.9% over 5m window]     |
+| Error rate      | [e.g. Sentry, Datadog]  | [> 1% of requests]           |
+| Latency (p99)   | [e.g. Prometheus+Grafana]| [> 500ms]                    |
+| CPU / Memory    | [e.g. CloudWatch]       | [> 80% sustained 5m]         |
+| Disk usage      | [e.g. node-exporter]    | [> 85%]                       |
+| [custom metric] | [tool]                  | [threshold]                   |
+
+- **On-call rotation:** [Describe who gets paged and escalation path]
+- **Dashboards:** [List key dashboards and what they show]
+- **Log aggregation:** [e.g. ELK, Loki, CloudWatch Logs — retention policy]
+
+## Security & Compliance
+- **Network:** [VPC layout, public/private subnets, security groups]
+- **Secrets management:** [How secrets are stored, rotated, and accessed]
+- **TLS:** [Certificate provisioning — Let's Encrypt, ACM, etc.]
+- **Access control:** [IAM roles, RBAC, least-privilege approach]
+- **Scanning:** [Container image scanning, dependency audit, SAST]
+- **Backup & DR:** [Backup schedule, RTO/RPO targets, disaster recovery plan]
+- **Compliance:** [SOC2, GDPR, HIPAA — list applicable standards]
+
+## Implementation Phases
+
+### Phase 1 — Foundation
+- [ ] IaC repository setup and state backend
+- [ ] Networking (VPC, subnets, security groups)
+- [ ] Container registry and base image
+- [ ] CI pipeline (lint, test, build)
+- [ ] Development environment provisioning
+
+### Phase 2 — Deployment Pipeline
+- [ ] Staging environment provisioning
+- [ ] Automated deployment to staging
+- [ ] Database provisioning and migration strategy
+- [ ] Secrets management integration
+- [ ] Production environment provisioning
+
+### Phase 3 — Observability & Hardening
+- [ ] Monitoring stack deployment
+- [ ] Alerting rules and on-call setup
+- [ ] Log aggregation and retention
+- [ ] Security scanning in CI
+- [ ] Backup automation and DR drill
+- [ ] Runbook documentation for incident response