agentleFS
sametcelikbicaksametcelikbicak/opencode-team/skills/team-build/SKILL.md

team-build

Skill69 starsChanged 19 days agoMITView on GitHub

The build and TDD playbook for this team. Red-green-refactor, test-first vertical slices, seams, test pyramid, mocking at boundaries, deterministic tests and definition of done.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Read tests.md for examples and mocking.md for boundary guidelines.

    line 10
  2. Distinctive:

    Ask: "What is the public interface, and which seams should we test?" Give each proposed seam a one-line note on what it catches and what it …

    line 36
  3. Distinctive:

    Do not write e2e for everything.

    line 48
  4. Distinctive:

    Do not hide a race condition by raising a timeout.

    line 65
  5. Distinctive:

    Every acceptance criterion in the ticket has at least one test that maps to it.

    line 71
  6. Distinctive:

    No test was skipped, deleted, loosened or given a longer timeout to get green.

    line 74
  7. Distinctive:

    No known failing case is hidden.

    line 76
  8. Very specific:

    After implementation and tests are green, write your specialist report — .team/07-build-fe.md for frontend, .team/07-build-be.md for …

    line 80

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Build: Test-Driven Development

TDD is the red → green → refactor loop. This skill is the reference that makes that loop produce tests worth keeping: what a good test is, where tests go, what to mock, how to keep tests deterministic, and when the build is done.

Read tests.md for examples and mocking.md for boundary guidelines.

Before the first test, read the ticket in .team/03-backlog.md and the contract in .team/06-architecture.md. The acceptance criteria and the API contract are the source of truth, not the implementation you are about to write. Use the project's domain vocabulary so test names match the product language.

The loop

  1. Red — write one failing test for one acceptance criterion. Run it and see it fail for the right reason.
  2. Green — write only enough code to pass that test. Do not anticipate the next test or add speculative features.
  3. Refactor — with the test still green, remove duplication in the production code and the test. Keep the public contract unchanged.

One seam, one test, one minimal implementation per cycle. If a refactor changes module boundaries, the API contract or the data model, stop: that is an architecture change for the team-architecture skill (SKILL.md) and belongs in the next cycle, not hidden inside a green step.

What a good test is

Tests verify behavior through public interfaces, not implementation details. Code can change entirely; tests should not. A good test reads like a specification: "user can checkout with valid cart" tells you exactly what capability exists, and it survives refactors because it does not care about internal structure.

A test is the verification of an acceptance criterion, not proof that a line of code ran. Coverage percentage is not the goal; reliability is.

See tests.md for good and bad examples.

Seams: where tests go

A seam is the public boundary you test at: the interface where you observe behavior without reaching inside. Tests live at seams, never against internals.

Test only at pre-agreed seams. Before writing tests, write down the seams under test and confirm them with the user. No test is written at an unconfirmed seam. You cannot test everything, so agreeing the seams up front is how testing effort lands on critical paths and complex logic instead of every edge case.

Ask: "What is the public interface, and which seams should we test?" Give each proposed seam a one-line note on what it catches and what it misses.

When the shape of that interface is itself in question — how deep the module is, where the seam belongs, what it should expose — consult the team-architecture skill (SKILL.md). Its module boundaries and API contract define the seams; do not invent a second interface just for tests.

The test pyramid

TypeWhat it testsRatioSpeed
UnitBusiness logic, edge cases70%ms
IntegrationDB, API, file system, external boundary adapters20%s
e2eThe user journey10%s–min

Do not write e2e for everything. e2e is fragile and slow; use it only for the main journeys that bring in money.

Anti-patterns

  • Implementation-coupled: mocks internal collaborators, tests private methods, or verifies through a side channel (querying the database instead of using the interface). The tell: the test breaks when you refactor but behavior has not changed.
  • Tautological: the assertion recomputes the expected value the way the code does (expect(add(a, b)).toBe(a + b), a snapshot derived by hand the same way, a constant asserted equal to itself), so it passes by construction and can never disagree with the code. Expected values must come from an independent source of truth: a known-good literal, a worked example, the spec.
  • Horizontal slicing: writing all tests first, then all implementation. Bulk tests verify imagined behavior: you test the shape of things rather than user-facing behavior, the tests go insensitive to real changes, and you commit to test structure before understanding the implementation. Work in vertical slices instead: one test → one implementation → repeat, each test a tracer bullet that responds to what the last cycle taught you.
  • Weakening the test: deleting or loosening an assertion to make a test pass. See "Definition of done".

Deterministic tests

A test that depends on the clock, the network, random data or execution order is a flaky test. Flaky tests train the team to ignore red.

  • Fix time with the test framework's fake clock, or inject a clock. Never assert against Date.now().
  • Seed randomness, or inject the random source.
  • Mock only the external boundary (see mocking.md); never reach the real network in a unit test.
  • Each test creates its own state and cleans it up. Tests must pass in any order and in parallel where the runner allows.
  • Do not hide a race condition by raising a timeout. Fix the cause or mark the test as an explicit known issue.

Definition of done

The build is done only when all of these are true:

  • Every acceptance criterion in the ticket has at least one test that maps to it.
  • Each test was seen failing before the implementation that made it pass.
  • The full suite passes, deterministically, in the project's configured command.
  • No test was skipped, deleted, loosened or given a longer timeout to get green.
  • Tests are versioned next to the code they verify.
  • No known failing case is hidden. If something cannot be tested, say why in the build report.

Handoff to QA

After implementation and tests are green, write your specialist report — .team/07-build-fe.md for frontend, .team/07-build-be.md for backend:

  • What was built, per ticket and per acceptance criterion.
  • Tests added, with the criterion each one covers.
  • Exact commands run and their exact output (or "not run").
  • Known gaps, shortcuts and risks.

The orchestrator consolidates the specialist reports into .team/07-build.md after every requested specialist has completed successfully. Do not write the consolidated report yourself.

Then hand off to the QA stage: the qa agent (agents/qa.md) reads .team/06-architecture.md and .team/07-build.md, follows the team-qa skill (SKILL.md), and independently verifies the acceptance criteria. Do not report the QA stage as passed from the build stage; only QA can do that.

Adapted from the MIT-licensed test-driven development skill by Matt Pocock. See THIRD_PARTY_NOTICES.md.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.