The Canonical Specification

specs/<state>/<NNNN>-<slug>/spec.md is the single normative source for a slice of work. The parallel files plan.md, tasks.md, research.md and data-model.md are not used. The file is created from the template fireskills/skills/templates/Spec.md by iniciar_spec.mjs; you do not write it from scratch.

Directory structure

specs/
├── inbox/
│   └── 2026-09-18-174245-convite-de-membros-por-e-mail.md
├── backlog/
│   └── 0001-convite-de-membros-por-e-mail.md
├── milestones/            (only when an MVP is imported)
├── draft/
├── defined/
├── planned/
├── in-progress/
├── review/
└── completed/
    └── 0001-convite-de-membros-por-e-mail/
        ├── spec.md
        └── research/      (optional)

• inbox/ and backlog/ hold notes and briefs; they are not normative.
• A spec exists in exactly one state folder; the folder is the operational state.
• research/ holds only evidence that was actually consulted (copies, snapshots, contracts, examples) and is indexed inside spec.md. It holds no production code or tests.
• Nothing else is allowed in the spec package.

The header

A two-column Markdown table, Campo / Valor (do not convert it to **Campo**: valor lines). Real output of iniciar_spec.mjs:

# Especificação integrada: Convite de membros por e-mail

| Campo | Valor |
| --- | --- |
| Formato | Specsfy/2.0 |
| ID | SPEC-0001 |
| Slug | 0001-convite-de-membros-por-e-mail |
| Status | Draft |
| Effort | 1 |
| Effort updated at | 2026-09-18 |
| Effort rationale | Estimativa inicial; revisar durante a descoberta. |
| ClickUp Task | |
| Milestones | |
| Definition Gate | Pending |
| Plan Gate | Pending |
| Delivery Gate | Pending |
| Evidence Contract | 1 |
| Interface para pessoas | A definir |
| Atualizada em | 2026-09-18 |

Status follows the folder: Draft, Defined, Planned, Implementing, Reviewing, Complete. Interface para pessoas is Sim or Não; Sim makes section 10 mandatory.

The three acts and 18 sections

IDs are three digits and never renumbered: US-001, FR-001, NFR-001, AC-001, DEC-001, tasks T001.

Scenarios (section 6)

Each AC is a heading, a **Cobre** line with the IDs it covers, and a Gherkin block:

#### AC-001 — [comportamento]

**Cobre**: US-001, FR-001, NFR-001

```gherkin
@US-001 @FR-001 @NFR-001 @AC-001
Feature: [capacidade observável]

  Scenario: [caminho feliz aceito]
    Given [estado inicial]
    When [ação]
    Then [resultado observável]
```

Gherkin lives only here. No .feature file is created or run.

Interface (section 10)

When there is a screen: stack and conventions, screens and responsibilities, information flow and navigation, menus, forms and actions, composition, the Vue and @nuxt/ui components chosen, states and accessibility, the CRUD contract (PageHeader, UTable with enterpriseTableUi, visible ID, row link, edit and delete) and the visual review.

Tasks (section 14)

- [ ] T001 [TEST] [TDD] [US-001] Derivar teste Vitest do BDD em layers/teams/shared/utils/abilities.test.ts — Refs: FR-002, AC-003 — Depends: none
  - [ ] **PREP**: …
  - [ ] **EXECUTE**: …
  - [ ] **VERIFY**: …
  - [ ] **VISUAL**: …
  - [ ] **EVIDENCE**: …
  - [ ] **IMPROVE**: …

A change to the database includes a [CODE] [MIGRATION] task pointing at a versioned file in apps/functions/src/database/migrations/.

Tests and traceability (sections 11–12)

Each executable Vitest case carries its own marker beside its definition:

// SPECSFY: US-001 FR-001 AC-001

The marker is a comment; it is not part of the test title. The Evidência RED-GREEN-REFACTOR table records each observed RED and GREEN.

Anti-patterns

• Creating plan.md, tasks.md, todo.md or any other parallel file.
• Tests without a // SPECSFY: marker, or one shared marker for a whole file (it counts as one case).
• A task without the six checklist items, or with VISUAL missing.
• Leaving template examples, TBD or TODO in a spec marked Defined.