Development Workflow: SDD → BDD → TDD → DDD

Purpose: Prevent implementation chaos through disciplined, spec-driven quality gates.
Philosophy: Specifications first, tests second, implementation last.
Result: Measurable progress, guaranteed quality, maintainable codebase.

Visual Overview

View source

Key Principle: Tests fail FIRST (red), then code makes them pass (green).

Detailed Flow:

Diagram Source of Truth: docs/diagrams/workflow-diagram.mermaid

To regenerate this diagram after editing the source:

pnpm run diagrams:fix

This will regenerate all .svg files from their corresponding .mermaid sources. See CONTRIBUTING.md#diagrams for details.

Why This Workflow?

The Problem

Software projects tend toward implementation chaos:

Features built without clear requirements
Tests written as afterthoughts (or not at all)
Technical debt accumulates silently
Regressions sneak in unnoticed
Architecture drifts from original intent

The Solution

Force structured gates at every milestone:

SDD — Define what we're building (specifications + decisions)
BDD — Define expected behavior (integration tests that FAIL)
TDD — Define contracts (unit tests that FAIL)
DDD — Implement until tests PASS

Gate: Cannot proceed to next phase until previous phase is complete and peer-reviewed.

The Four Phases

Phase 1: SDD (Specification Driven Development)

Goal: Document architectural decisions and component contracts BEFORE writing tests or code.

Sovereign Interoperability Gates:

WASM Components: Define capabilities in WIT (Wasm Interface Type).
Sovereign Graph: Define JSON-LD structures for semantic data portability.
Contract Interface: Define the TypeScript interface and conforming capability (e.g., storage:v1).

Artifacts:

ADRs (Architecture Decision Records) — Major technical choices
Specs — Component interfaces, data schemas, API contracts
Diagrams — Data flow, sequence diagrams, architecture overviews

Deliverables:

specs/
├── ADRs/
│   └── ADR-001-monorepo-structure.md
├── features/
│   └── storage-interface.md
└── diagrams/
    └── data-flow.mermaid

Quality Gate:

All architectural questions answered
Public interfaces documented
Data schemas defined (JSON-LD, WIT, TypeScript types)
At least 1 peer review on each ADR/spec
No "TODO" or "TBD" in critical sections

When to Skip: Never. Every milestone starts with SDD.

Phase 2: BDD (Behavior Driven Development)

Goal: Define expected behavior via integration tests and conformance suites before implementation.

Core Mechanics:

Conformance Suites: Use run[Contract]Conformance() helpers to validate interface compliance.
Integration Specs: Describe user scenarios (e.g., vitest unit tests acting as behavior specs).

Characteristic: Tests MUST FAIL initially (red phase).

Artifacts:

Integration test suites (e2e, component integration)
Acceptance criteria as executable tests
User scenario tests

Example:

// tests/integration/storage.spec.ts

describe("Offline-first storage", () => {
  it("persists data when offline", async () => {
    const storage = await createStorage({ offline: true });
    
    await storage.set("key", { value: "data" });
    
    // Simulate app restart
    await storage.close();
    const newStorage = await createStorage({ offline: true });
    
    const result = await newStorage.get("key");
    expect(result).toEqual({ value: "data" });
  });
  
  it("syncs data between 2 clients", async () => {
    const client1 = await createClient();
    const client2 = await createClient();
    
    await client1.set("key", "value1");
    await waitForSync();
    
    const result = await client2.get("key");
    expect(result).toBe("value1");
  });
});

Quality Gate:

All user-facing behaviors have tests
Tests are readable (describe user scenarios, not implementation)
Tests FAIL (red) because implementation doesn't exist yet
Coverage target defined (e.g., "all happy paths + 3 error cases")
Peer reviewed for completeness

When to Skip:

Small utility functions (use TDD only)
Internal refactors that don't change behavior
Documentation-only changes

Phase 3: TDD (Test Driven Development)

Goal: Write unit tests that define contracts for individual functions/classes.

Characteristic: Tests MUST FAIL initially (red phase).

Artifacts:

Unit test suites
Contract tests (interfaces, types)
Edge case coverage

Example:

// packages/storage-sqlite/src/crud.test.ts

describe("CRUD operations", () => {
  let db: Database;
  
  beforeEach(() => {
    db = createInMemoryDB();
  });
  
  describe("insert", () => {
    it("returns inserted ID", async () => {
      const id = await db.insert("users", { name: "Alice" });
      expect(id).toBeGreaterThan(0);
    });
    
    it("throws on duplicate primary key", async () => {
      await db.insert("users", { id: 1, name: "Alice" });
      await expect(
        db.insert("users", { id: 1, name: "Bob" })
      ).rejects.toThrow("UNIQUE constraint failed");
    });
  });
  
  describe("CRDT merge", () => {
    it("resolves conflicts with LWW", () => {
      const state1 = { value: "A", timestamp: 100 };
      const state2 = { value: "B", timestamp: 200 };
      
      const result = merge(state1, state2);
      
      expect(result.value).toBe("B"); // Last-Write-Wins
      expect(result.timestamp).toBe(200);
    });
  });
});

Quality Gate:

All public functions have unit tests
Edge cases covered (null, empty, boundary conditions)
Tests FAIL (red) because implementation is stub/missing
Coverage ≥80% for core logic
Fast execution (<1s for entire unit suite)

When to Skip:

Pure integration components (web servers, routers)
Thin wrappers around third-party libraries
UI components (use BDD with component tests instead)

Phase 4: DDD (Domain Driven Design & Implementation)

Goal: Write the minimal code necessary to make ALL tests pass while cultivating the "Solo Fértil".

Domain Layers:

Sovereign Nodes: Map concepts (Identity, Note) to the JSON-LD graph.
Tractor Policies: Orchestrate plugin interaction with user data.
Plugin Ingestion: Normalize external data into sovereign formats.

Characteristic: Tests transition from RED → GREEN.

Artifacts:

Production code
Domain models, services, repositories
Infrastructure adapters

Implementation Rules:

Start with simplest failing test
Write minimal code to make it pass
Refactor only when green
Repeat until all tests pass

Domain Organization:

packages/storage-sqlite/
├── src/
│   ├── domain/           # Core business logic
│   │   ├── storage.ts    # Storage interface (spec)
│   │   └── crud.ts       # CRUD operations
│   ├── infra/            # Infrastructure adapters
│   │   ├── sqlite-adapter.ts
│   │   └── opfs-adapter.ts
│   └── index.ts          # Public API
└── tests/
    ├── unit/
    └── integration/

Quality Gate:

All BDD tests pass (green)
All TDD tests pass (green)
No skipped/pending tests
Code coverage meets target (≥80%)
No linting errors
Peer reviewed (code + architecture alignment with specs)
Changeset created (pnpm run changeset)

When to Skip: Never. DDD is the final step where code is written.

Quality Gates Summary

Phase	Entry Criteria	Exit Criteria	Can Skip?
SDD	Milestone defined	ADRs + specs complete, peer reviewed	❌ Never
BDD	SDD complete	Integration tests written (RED), peer reviewed	⚠️ Small utilities only
TDD	BDD complete	Unit tests written (RED), peer reviewed	⚠️ Pure integration components
DDD	TDD complete	All tests GREEN, coverage met, changeset created	❌ Never

Example: Full Cycle for `storage-sqlite`

1. SDD Phase

Deliverable: specs/features/storage-interface.md

# Storage Interface Specification

## Purpose
Provide offline-first persistence via SQLite/OPFS.

## Public API
```typescript
interface Storage {
  get(key: string): Promise<unknown>;
  set(key: string, value: unknown): Promise<void>;
  delete(key: string): Promise<void>;
  close(): Promise<void>;
}

Architecture Decision

ADR-002: Use SQLite WASM + OPFS for browser persistence
ADR-003: Virtual file system via sql.js VFS


**Gate**: ✅ Peer reviewed, no open questions.

---

### 2. BDD Phase

**Deliverable**: `packages/storage-sqlite/tests/integration/storage.spec.ts`

```typescript
describe("Storage", () => {
  it("persists data across restarts", async () => {
    const storage = await createStorage();
    await storage.set("key", "value");
    await storage.close();
    
    const newStorage = await createStorage();
    expect(await newStorage.get("key")).toBe("value");
  });
});

Status: 🔴 FAILING (storage not implemented yet)

Gate: ✅ Test is clear, peer reviewed.

3. TDD Phase

Deliverable: packages/storage-sqlite/src/crud.test.ts

describe("CRUD", () => {
  it("insert returns ID", async () => {
    const id = await db.insert("table", { data: "value" });
    expect(id).toBeGreaterThan(0);
  });
});

Status: 🔴 FAILING (db.insert is a stub)

Gate: ✅ Contract tests complete, peer reviewed.

4. DDD Phase

Deliverable: packages/storage-sqlite/src/crud.ts

export async function insert(
  db: Database,
  table: string,
  data: Record<string, unknown>
): Promise<number> {
  const keys = Object.keys(data);
  const values = Object.values(data);
  const placeholders = keys.map(() => "?").join(",");
  
  const sql = `INSERT INTO ${table} (${keys.join(",")}) VALUES (${placeholders})`;
  const result = await db.run(sql, values);
  
  return result.lastInsertRowid;
}

Status: 🟢 PASSING (all tests green)

Gate: ✅ Tests pass, coverage 85%, changeset created.

Workflow in Practice

Fast Operator Loop (Canonical)

Use this loop at the start and end of each slice to keep execution aligned with current runtime state.

# start of slice
refarm resume --json
refarm check --next-action --json

# after source edits
refarm agent finish --lane after-edit --run --json

# after commit
refarm agent finish --lane after-commit --run --json

Actionability rule: every feature/ADR should provide at least one explicit BDD red command, one TDD red command, and one full green verification command.

Optional drift check for active docs/specs in your current diff:

pnpm run docs:actionability:check

This command is advisory by default (does not fail your lane).

Full repository scan (heavier, use before large docs sweeps):

pnpm run docs:actionability:check:all

If you want a blocking gate, use strict mode explicitly:

pnpm run docs:actionability:check:strict
pnpm run docs:actionability:check:all:strict

Starting a New Milestone

# 1. Start a new task using the Developer Toolbox
pnpm run task:start

# > Select "Feature / Issue Mode"
# > Enter GitHub Issue ID: 42
# > Linked to: "identity provider implementation"
# > Do you want to initialize an SDD Spec? (Y) -> vim specs/features/identity-provider.md
# > Does this feature require an ADR? (Y) -> vim specs/ADRs/ADR-004-identity-provider.md

# 2. Write integration tests (BDD)
vim packages/identity-nostr/tests/integration/identity.spec.ts

# 3. Verify Quality Gates (should FAIL / RED)
pnpm run task:verify

# 4. Write unit tests & Implement (TDD & DDD)
vim packages/identity-nostr/src/keypair.test.ts
vim packages/identity-nostr/src/keypair.ts

# 5. Verify Quality Gates (should PASS / GREEN)
pnpm run task:verify

# 6. Finish Task
# This automates running `task:verify`, changeset generation, commits, and pushes
pnpm run task:finish

# 7. Open PR
# The finish script suggests: gh pr create --title "finish: work on #42" --fill --body "Fixes #42"

Comandos do Toolbox

pnpm run task:start (Inicia uma branch BDD guiada)
pnpm run task:verify (Roda os Lint/Tests/Crates Checks)
pnpm run task:finish (Gera changesets e abre o Pull Request orgânico)
pnpm run task:rebrand (Renomeia a marca e domínios em caso de necessidade extrema)

Enforcing Gates in CI/CD

GitHub Actions Workflow

name: Quality Gates

on: [pull_request]

jobs:
  sdd-gate:
    if: contains(github.event.pull_request.labels.*.name, 'phase:sdd')
    steps:
      - name: Check ADRs exist
        run: |
          test -f specs/ADRs/ADR-*.md || exit 1
      
      - name: Check TODOs in specs
        run: |
          ! grep -r "TODO\|TBD" specs/ || exit 1
  
  bdd-gate:
    if: contains(github.event.pull_request.labels.*.name, 'phase:bdd')
    steps:
      - name: Run integration tests
        run: pnpm run test:integration
      
      - name: Ensure tests fail (red phase)
        run: |
          pnpm run test:integration && exit 1 || exit 0
  
  tdd-gate:
    if: contains(github.event.pull_request.labels.*.name, 'phase:tdd')
    steps:
      - name: Run unit tests
        run: pnpm test
      
      - name: Check coverage ≥80%
        run: pnpm run test:coverage -- --min-coverage=80
  
  ddd-gate:
    if: contains(github.event.pull_request.labels.*.name, 'phase:ddd')
    steps:
      - name: Run all tests
        run: pnpm test
      
      - name: Ensure tests pass (green phase)
        run: pnpm test
      
      - name: Check changeset exists
        run: |
          test -n "$(ls .changeset/*.md 2>/dev/null | grep -v README)" || exit 1
      
      - name: Lint
        run: pnpm run lint
      
      - name: Build
        run: pnpm run build

Anti-Patterns to Avoid

❌ Writing code before specs

// ❌ BAD: Started implementing without spec
class Storage {
  // ... 300 lines of code ...
  // Wait, what was the interface supposed to be?
}

❌ Tests after implementation

// ❌ BAD: Tests written to match existing code (not behavior)
it("returns undefined when key not found", () => {
  // This is testing implementation detail, not requirement
  expect(storage.get("missing")).toBe(undefined);
});

❌ Skipping tests for "simple" code

// ❌ BAD: "This function is too simple to test"
function merge(a, b) {
  return { ...a, ...b };  // Actually has subtle bugs with nested objects
}

❌ Merging failing tests

// ❌ BAD: "I'll fix the tests later"
describe.skip("Sync tests", () => {
  // Tests that don't pass yet
});

When to Revisit SDD

SDD isn't "set and forget." Return to SDD when:

Architecture assumptions are wrong (PoC reveals blocker)
Requirements change (new user needs discovered)
Technology choice fails (performance, compatibility issues)
Scope expands (new features need new decisions)

Process: Create amendment ADR, update specs, propagate changes to BDD/TDD.

Example:

specs/ADRs/
├── ADR-002-storage-strategy.md         # Original
└── ADR-002-storage-strategy-AMENDED.md  # Revised after PoC

Summary

Phase	Purpose	Deliverable	Test Status
SDD	What to build	ADRs + Specs	N/A
BDD	Expected behavior	Integration tests	🔴 RED
TDD	Component contracts	Unit tests	🔴 RED
DDD	Implementation	Production code	🟢 GREEN

Key Insight: Tests fail FIRST (red), then code makes them pass (green). This prevents:

Implementing wrong features
Skipping edge cases
Accumulating technical debt
Regressions going unnoticed

Result: Predictable, measurable progress toward high-quality software.

� Branch & Release Flow

Branch Model

feature/xyz ──┐
feature/abc ──┤──► develop ──► main ──► (packages published)
fix/yyy ───────┘       ▲                      │
                       │                      │
                       └──── auto-rebase ◄────┘

main — produção, protegido. Nunca recebe push direto.
develop — integração contínua. Base para todas as feature branches.
feature/*, fix/*, docs/* — ramificam de develop, voltam para develop via PR.

Ciclo completo de uma feature

# 1. Criar branch a partir de develop
git checkout develop && git pull origin develop
git checkout -b feature/minha-feature

# 2. Trabalhar, commitar, push
git push origin feature/minha-feature

# 3. Abrir PR → develop  (CI: testes, lint, type-check, changeset)
# 4. Merge em develop (qualquer estratégia funciona)

# 5. Quando develop estiver pronto para release:
#    Abrir PR: develop → main  
# 6. Aprovar e mergear usando uma estratégia permitida pelo repositório.
#    Preferir histórico linear quando disponível; squash release também é suportado.

# 7. ✅ O workflow sync-develop.yml alinha develop ao baseline de main.
#    Não é necessário nenhuma ação manual quando não há divergência real de conteúdo.

Estratégia de merge

Em develop: qualquer estratégia funciona (squash, rebase, ou merge commit) para integrar branches curtas.
Em main: usar a estratégia permitida pela proteção do repositório. Quando develop → main for squashado, main terá um commit novo com a mesma árvore de develop.
O workflow sync-develop.yml não rebaseia nem reescreve develop automaticamente. Após qualquer push em main, ele:
1. não faz nada se develop já aponta para main;
2. faz fast-forward se develop é ancestral de main;
3. abre issue quando develop e main têm a mesma árvore, mas histórico diferente (caso típico de squash/rebase release);
4. abre issue e falha quando há divergência real de conteúdo.

Quando a proteção do repositório exigir squash ou rebase no PR develop → main, trate o alinhamento posterior de develop como uma decisão manual. Isso preserva a história atômica de develop até alguém optar conscientemente por reset, rebase ou outro alinhamento com backup.

Release via Changesets

Changesets acumulam em develop durante o sprint (arquivo em .changeset/).
Após o merge develop → main, o workflow release-changesets.yml cria automaticamente um PR de versão (chore(release): version packages) no main.
Após esse PR ser aprovado, mergear com rebase também para manter linear.
Os pacotes são publicados no npm/crates.io.
O sync-develop.yml alinha develop novamente ao baseline de main usando fast-forward ou equivalência de árvore.

Observação pós-push (ritual curto)

Após git push origin develop em lote relevante, acompanhar CI com:

gh run list --branch develop --limit 5
gh run watch --exit-status

Se gh não estiver disponível no ambiente, registrar no handoff:

hash pushado,
checks esperados,
owner humano que ficará observando o CI.

Sync automático falhou?

O workflow só deve falhar quando develop e main divergem por conteúdo. Isso geralmente significa que houve trabalho simultâneo em main e develop que precisa de decisão humana. Fix manual:

git fetch origin
git checkout develop
git diff --stat origin/main..origin/develop
git log --oneline --left-right origin/main...origin/develop

Depois escolha conscientemente entre merge, rebase ou reset, conforme a intenção da divergência. Não use force-push apenas para silenciar o workflow; force-push só é seguro quando a equivalência de árvore foi confirmada ou quando o owner decidiu descartar explicitamente a divergência.

Preflight obrigatório (go/no-go)

Antes de qualquer lote paralelo (colônia, swarm ou macro-refactor), execute:

Preflight rápido (obrigatório)

node scripts/reso.mjs status
pnpm run project:validate
pnpm run factory:preflight

Preflight completo (quando tocar runtime/host security)

cd packages/tractor
cargo check --quiet
cargo test --lib agent_tools_bridge --quiet
cargo test --lib plugin_host --quiet
cargo test --lib wasi_bridge --quiet
pnpm run test:smoke:ws

Critério de go/no-go

GO: todos os checks do preflight rápido verdes; se houver mudança de boundary runtime, preflight completo verde.
NO-GO: qualquer falha em toolchain/targets/permissão/reso status → corrigir ambiente antes de abrir lote.

Sinais objetivos para migrar para melhoria funcional de produto

Use esta regra de passagem quando a equipe estiver em ciclo de ajustes de pipeline/processo:

Condição de estabilidade (últimos 3 lotes):
- Nenhum timeout de pre-push local crítico em lint/type-check/test (warnings locais aceitáveis, desde que documentados);
- Sem falha bloqueante repetida de prepush após ajuste de mesma categoria;
- refarm check --next-action --json sem bloqueios funcionais;
- pre-push passou sem novos arquivos/patches com impacto direto sobre o fluxo básico (testes de regressão, preflight e CI alinhados).
Condição de transição de trabalho:
- Abra explicitamente um novo ticket/objetivo funcional;
- Mantenha o estado atual de validação como baseline (git log + evidência de checks);
- A próxima entrega começa com um requisito/escopo de produto por vez (1 feature, 1 PR).
Regra de segurança: se após 1 ciclo funcional surgir novamente pressão de recursos (zumbi, travamentos, timeouts), retorne para o bloco de estabilização com objetivo único e timeout de execução explícito.

Autorização explícita para escrita em lote

Para evitar ambiguidade operacional, use confirmação textual explícita antes de ações de escrita em lote:

Formato recomendado: AUTORIZO: executar lote <escopo> com commits.
Sem autorização explícita, limitar execução a leitura/diagnóstico.

Gate de validação: smoke + full

Smoke gate (por task/PR)

Objetivo: feedback rápido por mudança atômica.

Rodar apenas o subconjunto afetado (ex.: boundary package + testes diretos).
Exigir evidência objetiva no PR/handoff (comando + resultado).

Full gate (integração de lote)

Objetivo: garantir que o conjunto integrado não regrediu.

Rodar pipeline completo de qualidade definido no repositório (local e/ou CI).
Consolidar evidências em .project/verification.json.

Regra prática:

Task PR: smoke obrigatório.
Merge de lote / boundary sensível: smoke + full obrigatórios.

Formato padrão de evidence (`.project/verification.json`)

Campos obrigatórios por entrada de verificação:

id
target
target_type
status
method
timestamp
evidence
criteria_results[]

Exemplo mínimo:

{
  "id": "VER-EXAMPLE-001",
  "target": "T-PIPE-02",
  "target_type": "task",
  "status": "passed",
  "method": "test",
  "timestamp": "2026-04-24T12:00:00.000Z",
  "evidence": "Comandos smoke executados com resultado verde.",
  "criteria_results": [
    {
      "criterion": "Type-check passa nos pacotes Foundation",
      "status": "passed",
      "evidence": "gate:smoke:foundation verde"
    }
  ]
}

Source Sovereignty & Hygiene

1. Tracking Policy: Source vs. Derivatives

To avoid repository bloating and ensure reproducibility:

Track Only Source: .ts, .wit, .ld.json, .md.
Ignore Derivatives: .js, .d.ts, binary .wasm (managed by CI/build).
Cleanup: Run pnpm run clean:derivatives to purge ignored artifacts.

2. Dual-Mode Resolution (`reso.mjs`)

The project supports a dynamic resolution switcher to balance speed and rigor:

Source Mode (node scripts/reso.mjs src): Instant DX with direct src/ imports.
Dist Mode (node scripts/reso.mjs dist): CI/Release verification against build artifacts.

3. Política operacional src/dist (obrigatória)

Durante iteração diária, operar em reso src.
Antes de merge em branch protegida, validar em reso dist.
node scripts/reso.mjs status é obrigatório no início da task e antes de finalizar PR.

Fluxo mínimo recomendado:

# início da task
node scripts/reso.mjs status
node scripts/reso.mjs src

# validação final
node scripts/reso.mjs dist
pnpm run type-check
pnpm run test:unit
node scripts/reso.mjs status

Planejamento da colônia (baseline de execução)

Macro-domínios e ownership (paralelização segura)

Domínio	Ownership sugerido	Pacotes/arquivos principais	Regra de concorrência
Runtime Core	worker-runtime	`packages/tractor/`, `packages/tractor-ts/`	serializar por boundary
Contracts & Storage/Sync	worker-contracts	`packages/-contract-v1/`, `packages/storage-/*`, `packages/sync-/**`	até 2 workers em pacotes distintos
Plugin Platform	worker-plugin	`packages/plugin-manifest/`, `packages/barn/`	serializar mudanças no contrato
Governance & CI	worker-governance	`.project/`, `.github/workflows/`, `docs/**`	1 worker por vez em `.project` e workflows

Granularidade padrão de task (PR pequeno e revisável)

Meta de diff por task: até 300 linhas adicionadas/modificadas (quando possível).
Meta de arquivos por task: até 8 arquivos (exceto mudanças de teste/documentação associadas).
Cada task deve incluir:
- objetivo único,
- critérios de aceite objetivos,
- comando de validação smoke.

Template mínimo de acceptance criteria:

- Comportamento X validado
- Regressão Y coberta em teste
- Evidência registrada em verification

Fila inicial de 2 semanas (ordem e dependências)

Semana 1 (estabilização de fluxo):

T-ENV-03 preflight de ambiente
T-ENV-04 política src/dist
T-PIPE-01 baseline de type-check
T-PLAN-01 macro-domínios e ownership
T-PLAN-02 granularidade padrão

Semana 2 (execução paralela governada):

T-PLAN-03 fila de execução inicial
T-PLAN-04 anti-colisão/locks
T-PLAN-05 branch naming + commits atômicos
T-PLAN-06 limite de concorrência e escala
T-PLAN-07 prompt padrão para workers

Política anti-colisão (arquivos/pacotes críticos)

Pacotes/áreas serializadas:

packages/tractor/**
packages/tractor-ts/**
packages/plugin-manifest/**
.project/**
.github/workflows/**

Regra de lock operacional:

antes de iniciar task em área serializada, anunciar claim no handoff;
somente 1 task ativa por área serializada;
handoff de lock obrigatório ao trocar responsável.

Prompt de entrada padrão para workers

Template canônico: docs/superpowers/COLONY_WORKER_INPUT_TEMPLATE.md.

Templates complementares:

saída do worker: docs/superpowers/COLONY_WORKER_OUTPUT_TEMPLATE.md
pacote de templates para operação/review: docs/templates/COLONY_*_TEMPLATE.md

Prompt obrigatório deve conter:

objetivo,
escopo (arquivos permitidos),
restrições (source sovereignty, sem artefatos),
validação mínima (smoke/full),
critério de escalonamento (quando parar e pedir humano).

Ritual semanal de triagem de bloqueios

Cadência: 1x por semana (segunda-feira, 30min).

Roteiro:

listar tasks planned/in_progress com dependências quebradas;
classificar bloqueio: ambiente, dependência técnica, decisão pendente;
definir ação: desbloquear, reatribuir, escalonar para humano, ou cancelar;
atualizar .project/tasks.json + .project/handoff.json.

Critérios de desbloqueio:

dependência concluída e validada;
ambiente reproduzível no preflight;
decisão arquitetural registrada em .project/decisions.json.

Fluxo de reassign:

marcar owner atual no handoff,
reatribuir task no board,
anexar comando de retomada e último estado de validação.

Estratégia src/dist (quando alternar)

Use esta matriz rápida:

Situação	Modo recomendado	Motivo
Implementação diária / iteração curta	`reso src`	DX e navegação direta ao código-fonte
Pré-merge em branch protegida	`reso dist`	valida superfície distribuível
Diagnóstico de ambiente	`reso status`	calibra estado real antes de agir
Mudança de topology alias	`reso sync-tsconfig`	mantém paths consistentes

Exemplo operacional:

node scripts/reso.mjs status
node scripts/reso.mjs src
# ...trabalho local...
node scripts/reso.mjs dist
pnpm run gate:smoke:foundation
node scripts/reso.mjs status

Escalonamento de bloqueios (runbook)

Quando escalar para humano:

conflito de decisão arquitetural sem ADR/DEC resolvida;
falha persistente de preflight após tentativa reprodutível;
colisão recorrente em área serializada.

Quando abrir/atualizar issue:

bloqueio reproduzível,
afeta múltiplas tasks,
não cabe no slice atual sem desvio de escopo.

Quando cancelar task:

requisito invalidado por decisão posterior,
caminho alternativo já aprovado,
custo/risco não justifica execução no ciclo atual.

See Also:

docs/COLONY_PLAYBOOK.md — Operação ponta-a-ponta (preflight, execução, consolidação)
docs/DEVELOPMENT_RESOLUTION.md — Estratégia detalhada src/dist
roadmaps/MAIN.md — How this workflow applies to releases
CONTRIBUTING.md — Developer workflow
specs/ADRs/ — Architecture decisions

Last Updated: April 2026

FilesExpand file tree

WORKFLOW.md

Latest commit

History

WORKFLOW.md

File metadata and controls

Development Workflow: SDD → BDD → TDD → DDD

Visual Overview

Why This Workflow?

The Problem

The Solution

The Four Phases

Phase 1: SDD (Specification Driven Development)

Phase 2: BDD (Behavior Driven Development)

Phase 3: TDD (Test Driven Development)

Phase 4: DDD (Domain Driven Design & Implementation)

Quality Gates Summary

Example: Full Cycle for storage-sqlite

1. SDD Phase

Architecture Decision

3. TDD Phase

4. DDD Phase

Workflow in Practice

Fast Operator Loop (Canonical)

Starting a New Milestone

Comandos do Toolbox

Enforcing Gates in CI/CD

GitHub Actions Workflow

Anti-Patterns to Avoid

❌ Writing code before specs

❌ Tests after implementation

❌ Skipping tests for "simple" code

❌ Merging failing tests

When to Revisit SDD

Summary

� Branch & Release Flow

Branch Model

Ciclo completo de uma feature

Estratégia de merge

Release via Changesets

Observação pós-push (ritual curto)

Sync automático falhou?

Preflight obrigatório (go/no-go)

Preflight rápido (obrigatório)

Preflight completo (quando tocar runtime/host security)

Critério de go/no-go

Sinais objetivos para migrar para melhoria funcional de produto

Autorização explícita para escrita em lote

Gate de validação: smoke + full

Smoke gate (por task/PR)

Full gate (integração de lote)

Formato padrão de evidence (.project/verification.json)

Source Sovereignty & Hygiene

1. Tracking Policy: Source vs. Derivatives

2. Dual-Mode Resolution (reso.mjs)

3. Política operacional src/dist (obrigatória)

Planejamento da colônia (baseline de execução)

Macro-domínios e ownership (paralelização segura)

Granularidade padrão de task (PR pequeno e revisável)

Fila inicial de 2 semanas (ordem e dependências)

Política anti-colisão (arquivos/pacotes críticos)

Prompt de entrada padrão para workers

Ritual semanal de triagem de bloqueios

Estratégia src/dist (quando alternar)

Escalonamento de bloqueios (runbook)

Example: Full Cycle for `storage-sqlite`

Formato padrão de evidence (`.project/verification.json`)

2. Dual-Mode Resolution (`reso.mjs`)