Spec Kit for Golang Teams: Onboarding and a Shared Constitution

1Common problems:
2- "The spec lives in a Google Doc that's already 3 versions out of date"
3- "PR review takes forever because the reviewer doesn't have the context"
4- "The same feature gets implemented differently by different developers"
5- "A new developer needs 2 weeks to understand the codebase"
6- "It's unclear whether the implementation actually meets the requirement"

 1# Constitution-writing session (a workshop, not an individual task)
 2# Involve: tech lead, 2-3 senior developers, product
 3
 4specify constitution
 5
 6# Prompts:
 7# - "What architecture do we use, and why?"
 8# - "What naming conventions must everyone follow?"
 9# - "What is forbidden in this codebase?"
10# - "What does correct error handling look like?"

 1# Constitution: Santekno Shop
 2# Version: 2.0
 3# Last reviewed: 2026-07-01
 4# Reviewed by: @budi (tech lead), @andi, @citra, @dewi
 5
 6## Architecture Principles
 7
 8### Clean Architecture
 9Follow these layers (no exceptions):
101. Domain: entities, value objects, repository interfaces, usecase interfaces
112. UseCase: business logic, must not import repository implementations
123. Repository: persistence implementation, imports only the domain package
134. Delivery: HTTP handlers, imports usecase interfaces
14
15Dependency rule: outer layers may import inner layers, NEVER the reverse.
16Violation example: a usecase importing delivery/http = SERIOUS VIOLATION.
17
18### Error Handling
191. Repository: return (nil, nil) for not-found, not an error
202. UseCase: return domain error types (ErrNotFound, ErrForbidden, etc.)
213. Handler: map domain errors to HTTP status + JSON error code
224. Error code format: UPPERCASE_SNAKE_CASE
235. Error wrapping: always fmt.Errorf("context: %w", err)
24
25### Database
261. UUID for ALL primary keys
272. int64 cents for ALL monetary values (NOT float64)
283. Timestamps: timestamptz (not timestamp)
294. Soft delete: deleted_at TIMESTAMPTZ + deleted_by UUID
305. Connection: pgx/v5 ONLY (not database/sql)
316. Transactions: always use pgx.Tx for multi-table operations
32
33### API
341. REST: kebab-case for URL paths (/cancel-order, not /cancelOrder)
352. HTTP verbs: GET (read), POST (create), DELETE (delete), PUT (replace), PATCH (partial update)
363. Response: always JSON, Content-Type: application/json
374. Pagination: cursor-based for lists > 100 items (not offset)
38
39## Never Do
40
41- DON'T return database errors (pgx errors) to upper layers
42- DON'T use float64 for monetary values
43- DON'T import delivery from usecase or repository
44- DON'T skip error wrapping (always fmt.Errorf("%w", err))
45- DON'T use global state or singletons
46- DON'T panic inside a handler (only for the truly unrecoverable)
47
48## Required in Every PR
49
50- Spec reference (.specify/features/*/spec.md)
51- Test coverage >= 85%
52- specify audit --feature [name] PASS
53- go test -race passes
54- Zero golangci-lint warnings

 1## Developer Onboarding Checklist (Week 1)
 2
 3### Day 1: Context
 4- [ ] Read README.md
 5- [ ] Read CLAUDE.md (project context)
 6- [ ] Read .specify/constitution.md (mandatory principles)
 7- [ ] Set up the development environment
 8- [ ] Run tests: go test ./...
 9
10### Days 2-3: Codebase exploration via .specify
11- [ ] Read .specify/features/ — study 2-3 completed feature specs
12- [ ] Read one full plan.md + tasks.md
13- [ ] Trace spec -> code: follow an AC from spec.md to its implementation
14
15### Day 4: First task
16- [ ] Pick a small task from the backlog
17- [ ] Run specify feature for that task
18- [ ] Get review and approval from a senior developer
19- [ ] Implement with specify implement
20
21### Days 5-7: First PR
22- [ ] Finish the implementation
23- [ ] Run specify audit — confirm all ACs are implemented
24- [ ] Open a PR with a description from specify pr
25- [ ] Request review from a senior developer

 1# .speckit-config.yaml
 2
 3team:
 4  roles:
 5    product_manager:
 6      can_run: [feature, clarify]
 7      cannot_run: [implement, audit]
 8      description: "PM can write specs and take part in clarification"
 9
10    junior_developer:
11      can_run: [feature, clarify, plan, tasks, implement, audit]
12      requires_approval: [plan, implement]
13      description: "Junior can do everything, but plan and implement need senior approval"
14
15    senior_developer:
16      can_run: all
17      can_approve: [plan, implement]
18      description: "Senior can do everything and approve a junior's plan"
19
20    tech_lead:
21      can_run: all
22      can_approve: all
23      can_modify: [constitution, claude_md]
24      description: "Tech lead owns updates to the constitution and CLAUDE.md"

 1# Workflow with an approval gate
 2
 3# Developer: write the spec
 4specify feature
 5specify clarify
 6
 7# Create a spec review request
 8specify review-request --feature product-review --reviewers budi,dewi
 9
10# Tech lead / senior developer reviews:
11specify review --feature product-review
12
13# Output:
14# Review: product-review
15# Reviewer: @budi
16#
17# Checking spec quality...
18# All ACs have clear acceptance criteria
19# Edge cases are defined
20# Out of scope is explicitly stated
21# WARNING AC13 is ambiguous: "a valid order" — what makes it valid? PENDING? DELIVERED?
22# WARNING NFR missing: no performance requirement specified
23#
24# Decision: [approve/request-changes/reject]: request-changes
25# Comment: "Clarify AC13 and add a performance NFR"
26
27# Developer updates the spec and requests review again
28specify review-request --feature product-review --update

1# Create a template for a frequently built feature type
2specify template create --name crud-api
3# Template created at: .specify/templates/crud-api.md
4
5# Use the template when running specify feature:
6specify feature --template crud-api
7
8# The template is shared in git and updated together
9git commit .specify/templates/ -m "spec: add crud-api template with standard ACs"

 1# Template: CRUD API
 2# For: endpoints that Create, Read, Update, Delete
 3
 4## User Stories
 5[Define the User Story here]
 6
 7## Acceptance Criteria
 8
 9### Happy Path — Create
10- AC1: POST /[resources] accepts {[required fields]}
11- AC2: System validates [validation rules]
12- AC3: System stores with status [default status]
13- AC4: Response: 201 Created with [entity data]
14
15### Happy Path — Read (List)
16- AC5: GET /[resources] returns a paginated list
17- AC6: Response includes: total count, items, next cursor
18
19### Happy Path — Read (Single)
20- AC7: GET /[resources]/:id returns a single entity
21
22### Happy Path — Update
23- AC8: PUT /[resources]/:id accepts {[updateable fields]}
24- AC9: Response: 200 OK with the updated entity
25
26### Happy Path — Delete
27- AC10: DELETE /[resources]/:id deletes the entity
28- AC11: Response: 204 No Content
29
30### Error Cases
31- AC12: Invalid input -> 400 Bad Request + INVALID_[FIELD]
32- AC13: Entity not found -> 404 NOT_FOUND
33- AC14: Unauthorized -> 401 UNAUTHORIZED
34- AC15: Forbidden -> 403 FORBIDDEN
35
36## Edge Cases
37- EC1: Concurrent create/update (race condition)
38- EC2: DB failure (atomicity concern)
39
40## Out of Scope
41[List features NOT included in this PR]

 1# Generate team metrics from spec history
 2specify metrics --team --since "2026-06-01" --until "2026-07-01"
 3
 4# Output:
 5# Team Metrics — June 2026
 6#
 7# Features completed: 8
 8# ACs implemented: 112/115 (97.4%)
 9#
10# Per-developer:
11# @andi:  3 features, 42 ACs, avg 89% coverage, avg spec audit 96
12# @budi:  2 features (tech lead, lower count), 28 ACs, avg 94% coverage
13# @citra: 3 features, 42 ACs, avg 87% coverage, avg spec audit 94
14#
15# Deviation stats:
16# Most common: error code case mismatch (5 times)
17# Action: strengthen the constitution language
18#
19# Time metrics:
20# Avg spec phase: 45 min/feature
21# Avg implementation: 4.2 hr/feature
22# Avg review: 1.3 hr/feature
23# Total: 6 hr/feature (vs 12 hr estimate before Spec Kit)

 1# Create an RFC (Request for Constitution Change)
 2specify constitution-rfc --title "Add pgx advisory locks as a preferred pattern"
 3
 4# Output: .specify/rfcs/2026-07-01-pgx-advisory-locks.md
 5
 6# Team reviews on GitHub (PR/issue)
 7# Voting: at least 2 senior-dev approvals
 8
 9# After approval:
10specify constitution-apply --rfc 2026-07-01-pgx-advisory-locks
11
12# constitution.md is updated and all developers are notified

1# A feature spec that needs input from another team
2specify feature --feature cross-service-cancel-notification
3
4# Tag reviewers from multiple teams
5specify review-request --feature cross-service-cancel-notification \
6                       --reviewers @order-team/budi,@notification-team/eko
7
8# Cross-team review is captured in clarifications.md

 1# Before the sprint: generate specs for all stories to be worked on
 2for ticket in SHOP-789 SHOP-790 SHOP-791; do
 3    specify feature --ticket $ticket
 4done
 5
 6# Estimate from tasks.md across all stories
 7specify estimate --features "product-review,shipping-calc,flash-sale"
 8
 9# Output:
10# Sprint Estimation from Spec Kit:
11#
12# product-review:    14 tasks, 8.5 hr  (SHOP-789, @citra)
13# shipping-calc:      9 tasks, 5.5 hr  (SHOP-790, @andi)
14# flash-sale:        18 tasks, 11 hr   (SHOP-791, @budi+@andi)
15#
16# Total: 41 tasks, 25 hr
17# Team capacity (2 devs, 2 weeks): 40 hr
18#
19# Recommendation: flash-sale should be split or pushed to the next sprint

 1# Developer A writes the spec for a payment gateway
 2specify feature --feature payment-gateway
 3
 4# Developer B reviews and disagrees with AC5:
 5specify review --feature payment-gateway --reviewer andi
 6
 7# Review output from @andi:
 8# WARNING AC5: "3D Secure must always be enabled" — I disagree
 9#    Reason: 3D Secure adds friction; the business decided it should be optional
10#    Suggestion: "3D Secure is enabled based on the bank's requirement, can be optional"
11# Decision: request-changes
12
13# Resolution: a 30-minute meeting with the PM -> a new clarification in clarifications.md

 1# Developer A (Jakarta, 9am) writes the spec:
 2specify feature  # -> spec.md
 3
 4# Developer B (Singapore, different timezone) reviews async:
 5specify review --feature payment-gateway \
 6               --async \  # submit review without blocking
 7               --comments "Q1: Is 3D Secure mandatory?"
 8
 9# Developer A (next morning) sees the comments:
10specify review-status --feature payment-gateway
11# -> Pending review from @developer-b (Q1 submitted)
12
13# Answer async:
14specify clarify --answer "Q1: 3D Secure is optional, enabled per bank requirement"

 1# Onboarding comprehension test (for assessment):
 2specify quiz --constitution
 3
 4# Output: 10 questions based on the constitution
 5# Q1: If a repository gets a not-found from the DB, what should it return?
 6# A: nil, nil (not an error)
 7#
 8# Q2: What is the correct error code format?
 9# A: UPPERCASE_SNAKE_CASE (PURCHASE_REQUIRED, not purchase_required)
10#
11# A new developer can self-assess before their first PR

 1# Generate a team dashboard
 2specify dashboard --team
 3
 4# Output (can be exported as HTML):
 5#
 6# Sprint Progress
 7# ########## 83% (10/12 features complete)
 8#
 9# Spec Compliance This Sprint
10# AC compliance: 97.4%
11# Coverage avg: 89%
12# Lint: 0 issues
13#
14# Pending Reviews
15# product-review: waiting on @budi's review (2 days)
16# flash-sale spec: waiting on @dewi's approval (1 day)
17#
18# Recent Merges
19# cancel-order (SHOP-456) — @andi — 2026-07-01
20# product-review (SHOP-789) — @citra — 2026-07-02

 1## Anti-Pattern 1: "Spec by Committee"
 2
 3Problem: 5 people edit spec.md at once -> incoherent spec
 4Fix: One spec writer, one reviewer, one approver (RACI model)
 5
 6## Anti-Pattern 2: "The Living Spec That's Never Approved"
 7
 8Problem: Spec keeps getting edited after implementation starts -> scope creep
 9Fix: Spec-lock before specify plan — after plan, the spec is frozen
10
11## Anti-Pattern 3: "The Constitution Nobody Enforces"
12
13Problem: The constitution exists but violations have no consequences
14Fix: CI checks for constitution compliance + strict code review protocol
15
16## Anti-Pattern 4: "Specs Are Only for Juniors"
17
18Problem: Senior developers skip Spec Kit and go straight to coding
19Fix: Every developer, every level, follows the Spec Kit workflow

 1## Spec Kit Adoption Plan (4 weeks)
 2
 3### Week 1: Constitution and Setup
 4- Workshop: write constitution.md together (half a day)
 5- Setup: every developer installs the specify CLI
 6- Practice: each developer runs specify feature on a small existing feature
 7
 8### Week 2: Pilot Feature
 9- Pick one new feature as the pilot
10- Run the full workflow: specify -> clarify -> plan -> tasks -> implement
11- Retro: what worked, what needs adjusting
12
13### Week 3: Parallel Run
14- 2-3 features in parallel with Spec Kit
15- Senior developer support for each session
16
17### Week 4: Full Adoption
18- All new features must use Spec Kit
19- Update the PR template and CI for enforcement

 1# Monthly adoption metrics
 2specify metrics --adoption --month "2026-07"
 3
 4# Output:
 5# Spec Kit Adoption — July 2026
 6#
 7# Features completed: 12
 8# With Spec Kit: 10 (83.3%)
 9# Without Spec Kit: 2 (hotfixes - expected)
10#
11# Spec quality:
12# Avg ACs per feature: 9.4 (target: 8+)
13# Avg clarification Qs: 4.2 (good — thorough)
14#
15# Velocity impact:
16# Avg feature duration: 5.2 hr (vs 9.1 hr last month) -43%
17# PR review duration: 1.1 hr (vs 2.8 hr last month) -61%
18#
19# Adoption is growing! Target: 100% for August 2026.