# Tdd

> Create or update docs/TECHNICAL_DESIGN_DOCUMENT.md — testing strategy, dev environment, CI/CD, coding standards, linter/formatter choices. Use when the user asks to define testing strategy, set up CI/CD, pick linters/formatters, standardize the dev setup, or says 'how should we test this', 'what's our coding style', 'write the tech design doc', 'set up conventions for the repo'.

- **Type:** Skill
- **Install:** `agentstack add skill-0xrafasec-ai-workflow-tdd`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [0xrafasec](https://agentstack.voostack.com/s/0xrafasec)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [0xrafasec](https://github.com/0xrafasec)
- **Source:** https://github.com/0xrafasec/ai-workflow/tree/main/skills/tdd

## Install

```sh
agentstack add skill-0xrafasec-ai-workflow-tdd
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Create the Technical Design Document. Argument: $ARGUMENTS

## Context Gathering

Before interviewing, explore the project's current build and test setup:

1. **Check for existing docs:**
   - Read `docs/TECHNICAL_DESIGN_DOCUMENT.md` — if revising, don't start from scratch
   - Read `CLAUDE.md` for build/test commands
   - Read `docs/ARCHITECTURE.md` if it exists (for technology context)
   - Read `README.md` for setup instructions

2. **Explore the codebase:**
   - Look for test directories (`tests/`, `__tests__/`, `spec/`, `*_test.go`, `*.test.ts`, `test_*.py`)
   - Read `package.json`, `pyproject.toml`, `Cargo.toml`, `Makefile`, `docker-compose.yml` for tooling, test commands, dependencies
   - Read 1-2 existing test files to understand patterns (fixtures, helpers, naming)
   - Check for CI config (`.github/workflows/`, `.gitlab-ci.yml`, `Jenkinsfile`)
   - Check for linter/formatter config (`.eslintrc`, `ruff.toml`, `.golangci.yml`, `rustfmt.toml`)
   - Summarize what you found to the user before starting — "Here's what I see in the project: ..."

## Interview

Use AskUserQuestion to understand how the team builds, tests, and ships. Adapt based on what the codebase already reveals.

1. **Testing strategy** — What test frameworks are in use? Where do tests live? Are there separate unit/integration/e2e layers? What needs integration tests vs unit tests? Any critical flows that need e2e coverage?
2. **Dev environment** — How do developers set up locally? Docker, nix, manual install? What external services are needed (databases, queues, caches)?
3. **CI/CD pipeline** — What runs on every PR? What runs nightly? What gates block merging? How are deployments triggered?
4. **Coding standards** — Linter config, formatter, type checker? Any style guides or conventions not captured in tooling?
5. **Tooling decisions** — Package manager, build system, monorepo tools? Why these over alternatives?
6. **Error handling & observability** — Logging framework, error tracking, metrics? How do you debug production issues?
7. **Dependencies** — How are deps managed? Pinned versions? Vulnerability scanning? Update cadence?

For inherited projects, explore before asking — "I see you have pytest with a `tests/` folder but no integration tests yet — is that intentional?" and "Your CI runs `make test` but there's no lint step — is that by design?"

## Write

Write to `docs/TECHNICAL_DESIGN_DOCUMENT.md`:

```markdown
# Technical Design Document

**Version:** [version]
**Date:** [date]

## Testing Strategy

[This section is the source of truth that all other skills (/feature, /fix, /roadmap, /autopilot) reference when deciding what tests to write.]

### Test Layers

| Layer | Scope | Framework | Run Command | When to Write |
|-------|-------|-----------|-------------|---------------|
| Unit | Single function/module, no I/O | [e.g., pytest, vitest, go test] | [e.g., make test-unit] | Every change — business logic, pure functions, validators |
| Integration | Component boundaries, real dependencies | [e.g., pytest + testcontainers, supertest] | [e.g., make test-integration] | API endpoints, database queries, service interactions, middleware |
| E2E | Full user flows, production-like environment | [e.g., playwright, cypress, k6] | [e.g., make test-e2e] | Critical user paths, auth flows, payment flows |

### Test Conventions

- **File location:** [e.g., `tests/unit/`, `tests/integration/`, `tests/e2e/` or colocated `__tests__/`]
- **Naming:** [e.g., `test_.py`, `.test.ts`, `_test.go`]
- **Fixtures/factories:** [where shared test helpers live]
- **Test database:** [how integration tests get a database — testcontainers, sqlite, etc.]
- **CI behavior:** [which layers run on PR, which run nightly]

### Coverage Expectations

- Unit tests: cover all business logic, validation, and error paths
- Integration tests: cover all API endpoints, database operations, and external service calls
- E2E tests: cover critical user journeys (list the 3-5 most important flows)

## Dev Environment

### Setup

[Step-by-step local setup. Prerequisites, install commands, env vars.]

### External Dependencies

| Service | Local Setup | Purpose |
|---------|------------|---------|
| [e.g., PostgreSQL] | [e.g., docker compose up] | [e.g., primary data store] |

## CI/CD Pipeline

### PR Checks

| Check | Command | Blocks Merge |
|-------|---------|-------------|
| [e.g., Lint] | [e.g., make lint] | Yes |
| [e.g., Unit tests] | [e.g., make test-unit] | Yes |
| [e.g., Integration tests] | [e.g., make test-integration] | Yes |
| [e.g., E2E tests] | [e.g., make test-e2e] | No (nightly) |

### Deployment

[How deployments are triggered. Environments, promotion strategy, rollback procedure.]

## Coding Standards

- **Linter:** [tool and config file]
- **Formatter:** [tool and config file]
- **Type checker:** [tool and config file]
- **Conventions not captured in tooling:** [anything humans need to know]

## Tooling

| Tool | Purpose | Why This Over Alternatives |
|------|---------|---------------------------|
| [tool] | [what it does] | [rationale] |

## Error Handling & Observability

- **Logging:** [framework, format, levels]
- **Error tracking:** [service, how errors are reported]
- **Metrics:** [what's measured, where dashboards live]

## Dependency Management

- **Package manager:** [tool]
- **Version strategy:** [pinned, ranges, etc.]
- **Vulnerability scanning:** [tool, frequency]
- **Update cadence:** [how often, who owns it]
```

Adapt the structure to the project. A small project may skip Observability. A monorepo may need per-package sections. Use judgment.

## After Writing

1. Present the document to the user for review. Iterate until they're satisfied.
2. Suggest next steps based on what exists:
   - No architecture doc? → "Define system structure with `/architecture`"
   - No threat model? → "Consider `/security` for the threat model"
   - Ready to build? → "Create feature specs with `/spec `, then `/roadmap`"

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [0xrafasec](https://github.com/0xrafasec)
- **Source:** [0xrafasec/ai-workflow](https://github.com/0xrafasec/ai-workflow)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-0xrafasec-ai-workflow-tdd
- Seller: https://agentstack.voostack.com/s/0xrafasec
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.