feat: bootstrap Spec Kit SDD workflow and TicketLab constitution
sonar / sonar (push) Skipped
sonar / sonar (pull_request) Successful in 41s
sonar / sonar (push) Skipped
sonar / sonar (pull_request) Successful in 41s
Add Spec Kit (cursor-agent), Constitution 1.0.1, Cursor skills/rules, and tooling docs so workshop agents follow Plane-backed SDD with versioned agent assets. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Cursor
@@ -0,0 +1,141 @@
|
||||
<!--
|
||||
Sync Impact Report
|
||||
- Version change: 1.0.0 → 1.0.1
|
||||
- Modified principles: none (clarification only)
|
||||
- Added sections: none
|
||||
- Removed sections: none
|
||||
- Follow-up TODOs:
|
||||
- TODO(RFC): no RFC pages found in Plane Workshop SDLC; confirm whether RFCs will be introduced
|
||||
- Gherkin: Plane page "TicketLab — Cenários Gherkin" authored from matriz + TL-01/02/03 (2026-08-11); linked on epic and stories
|
||||
-->
|
||||
|
||||
# TicketLab Constitution
|
||||
|
||||
## Core Principles
|
||||
|
||||
### I. Spec-Driven Development
|
||||
All implementation work MUST start from an identified Plane story (or task under that
|
||||
story). Before writing application code, the agent MUST complete specification,
|
||||
clarification of gaps, planning, and task decomposition for the approved scope.
|
||||
The agent MUST implement only that approved scope and MUST NOT expand into
|
||||
out-of-scope capabilities (for this increment: no frontend, auth, attachments,
|
||||
queues, RAG, dashboards, or production deploy unless a future approved story
|
||||
explicitly adds them).
|
||||
|
||||
**Rationale:** TicketLab is an SDD workshop laboratory; the Plane contract for
|
||||
agents and the epic require verifiable, scoped delivery rather than ad-hoc coding.
|
||||
|
||||
### II. Plane as Requirements Source
|
||||
Plane is the source of truth for stories, acceptance criteria, Gherkin scenarios,
|
||||
tasks, ADRs, and RFCs (when present). ADRs and RFCs act as binding constraints on
|
||||
design and implementation. Missing, ambiguous, or contradictory information MUST
|
||||
trigger a clarification request. Missing requirements MUST NOT be invented.
|
||||
|
||||
**Rationale:** The agent execution contract lists Gherkin/criteria, ADRs, and
|
||||
related artifacts ahead of code; inventing gaps breaks workshop control and
|
||||
traceability.
|
||||
|
||||
### III. End-to-End Traceability
|
||||
Every change MUST preserve a verifiable chain:
|
||||
|
||||
```text
|
||||
Story → acceptance criteria / Gherkin → spec → plan → tasks → code → tests → evidence → Pull Request
|
||||
```
|
||||
|
||||
Work items, Plane pages (ADRs, matriz, readiness, PR template), Spec Kit
|
||||
artifacts, tests, quality evidence, and the Pull Request MUST be correlatable.
|
||||
Orphan implementation without a Plane story reference is not allowed.
|
||||
|
||||
**Rationale:** The Plane matriz and PR template exist to keep epic, stories,
|
||||
ADRs, and evidence connected through delivery.
|
||||
|
||||
### IV. Behavior-Oriented Testing
|
||||
Gherkin scenarios and acceptance criteria in Plane are the origin of behavior
|
||||
tests. Each acceptance criterion MUST have verifiable evidence (automated test
|
||||
and/or recorded operational evidence as required by the story). Changes MUST
|
||||
preserve applicable existing tests. Tests MUST run before review and before
|
||||
opening a Pull Request. External dependencies MUST be exercised with
|
||||
deterministic fakes in the quality gate (no real LLM in CI gate), per ADR-004.
|
||||
|
||||
**Rationale:** The epic requires verifiable behavior via Vitest + Gherkin;
|
||||
ADR-004 mandates Vitest, ESLint, SonarQube Quality Gate, and fake/simulated
|
||||
external dependencies for the gate.
|
||||
|
||||
### V. Implementation Simplicity
|
||||
Deliver the smallest solution that fully satisfies the approved specification and
|
||||
binding ADRs. Reuse existing capabilities before introducing new abstractions.
|
||||
New dependencies, layers, or generalizations require demonstrated need from
|
||||
Plane artifacts. Simplicity does not waive validation, error handling, security
|
||||
constraints, or observability requirements.
|
||||
|
||||
**Rationale:** ADR-001 chooses a modular monolith walking skeleton; unnecessary
|
||||
complexity fights the laboratory goals and the agent rule to stay in scope.
|
||||
|
||||
### VI. Observability
|
||||
When a change touches an observed flow, the following minimum MUST hold
|
||||
(ADR-003 / TL-03):
|
||||
|
||||
- structured JSON logs (Pino);
|
||||
- Prometheus/OpenMetrics metrics (`GET /metrics`);
|
||||
- OpenTelemetry tracing with OTLP export;
|
||||
- correlation via `trace_id` / `request_id` between execution and evidence;
|
||||
- no ticket description, prompts, raw model responses, or secrets in logs or
|
||||
traces.
|
||||
|
||||
Cardinality of metric labels MUST remain controlled. Observability names and
|
||||
detail for a given story remain defined in that story and ADR-003—not invented
|
||||
here.
|
||||
|
||||
### VII. Quality Before Pull Request
|
||||
A Pull Request MUST NOT be opened without evidence of, as applicable to the
|
||||
change:
|
||||
|
||||
- TypeScript typecheck;
|
||||
- lint (ESLint);
|
||||
- tests (Vitest), including coverage when configured for the gate;
|
||||
- build;
|
||||
- SonarQube analysis with Quality Gate pass;
|
||||
- diff review;
|
||||
- adherence to the approved spec, plan, tasks, ADRs, and RFCs (when present);
|
||||
- operational evidence required by the story (for example JSON logs, metrics,
|
||||
OTLP spans) and alignment with the OpenAPI contract.
|
||||
|
||||
**Rationale:** TL-03.4, ADR-004, and the Plane PR template require build, lint,
|
||||
tests, Quality Gate, and observable evidence before merge review.
|
||||
|
||||
## Artifact Authority
|
||||
|
||||
| Authority | Governs |
|
||||
|-----------|---------|
|
||||
| This Constitution | Permanent development principles and process gates |
|
||||
| ADRs (and RFCs when present) in Plane | Specific technical decisions and constraints |
|
||||
| Plane stories + acceptance criteria / Gherkin | Requested behavior for an increment |
|
||||
| Spec Kit `spec.md` / `plan.md` / `tasks.md` | Derived working artifacts for an approved story; they MUST NOT contradict Plane or this Constitution |
|
||||
|
||||
Conflict resolution order: Constitution principles → accepted ADRs/RFCs → active
|
||||
story acceptance criteria/Gherkin → derived Spec Kit artifacts → implementation
|
||||
detail. Unresolved conflict MUST stop implementation and request clarification.
|
||||
|
||||
Stack and design choices (for example Node.js 22, TypeScript, Fastify, SQLite
|
||||
with better-sqlite3, LiteLLM OpenAI-compatible API, OpenAPI) are recorded in
|
||||
ADRs and Plane pages; they are not restated as mutable constitution clauses.
|
||||
|
||||
## Governance
|
||||
|
||||
1. This Constitution is the authority for permanent principles. Amending it
|
||||
requires an explicit change to `.specify/memory/constitution.md`, a Sync
|
||||
Impact Report, semantic version bump, and recorded ratification or amendment
|
||||
date.
|
||||
2. ADRs and RFCs remain in Plane. Do not copy them wholesale into this file;
|
||||
reference them as constraints.
|
||||
3. Stories, criteria, Gherkin, and tasks remain in Plane and define increment
|
||||
behavior.
|
||||
4. Versioning uses semantic versions:
|
||||
- MAJOR: incompatible removal or redefinition of principles/gates;
|
||||
- MINOR: new principle/section or material expansion;
|
||||
- PATCH: clarifications and non-semantic wording fixes.
|
||||
5. Compliance: reviews and Pull Requests MUST verify alignment with this
|
||||
Constitution, applicable ADRs/RFCs, and the active story evidence chain.
|
||||
6. First effective version was `1.0.0` (ratified 2026-08-11).
|
||||
|
||||
**Version**: 1.0.1 | **Ratified**: 2026-08-11 | **Last Amended**: 2026-08-11
|
||||
Reference in New Issue
Block a user