name = "nbspec-default"
version = 1
description = """
nbspec default workflow - notebook-resident proposal, delta \
specifications, designs, and reserved decisions; no tasks artifact \
(the work todo note is the live execution record)"""
[[artifacts]]
id = "proposal"
generates = "proposal.md"
description = "Proposal note outlining why the change is needed"
requires = []
required = true
instruction = """
Write the proposal note that establishes WHY this change is needed.
Sections:
- **Why**: The problem or opportunity. What does this solve? Why now?
- **What Changes**: Bullet list of changes. Be specific about new
capabilities, modifications, or removals. Mark breaking changes
with **BREAKING**.
- **Capabilities**: Which specifications will be created or modified.
New capabilities each become a specification note under
`specifications/<name>`; use kebab-case names. Modified
capabilities need a delta specification against the existing
document under the repository's specifications directory.
- **Impact**: Affected code, APIs, dependencies, or systems.
Keep it concise. Focus on the "why", not the "how" - implementation
detail belongs in a design note.
"""
[[artifacts]]
id = "specifications"
generates = "specifications/**/*.md"
target = "documentation/specifications"
description = "Delta specifications defining what the system should do"
requires = ["proposal"]
required = true
grammar = "delta-specification"
instruction = """
Write one specification note per capability listed in the proposal,
under the change's `specifications/<capability>` folder.
Delta operations (use ## headers):
- **ADDED Requirements**: new capabilities
- **MODIFIED Requirements**: changed behavior - include the FULL
updated requirement block
- **REMOVED Requirements**: deprecated features - include **Reason**
and **Migration**
- **RENAMED Requirements**: name changes only - use FROM:/TO: format
Format requirements:
- Each requirement: `### Requirement: <name>` followed by normative
text using SHALL or MUST (avoid should/may).
- Each scenario: `#### Scenario: <name>` with WHEN/THEN bullets.
- Scenarios MUST use exactly four hashtags.
- Every requirement MUST have at least one scenario.
Specifications should be testable - each scenario is a potential
test case.
"""
[[artifacts]]
id = "designs"
generates = "designs/**/*.md"
target = "documentation/designs"
description = "Technical design notes with implementation decisions"
requires = ["proposal"]
instruction = """
Write design notes under the change's `designs/<name>` folder when
the change is cross-cutting, introduces dependencies or new
architectural patterns, or carries security, performance, or
migration complexity.
Sections:
- **Context**: background, current state, constraints
- **Goals / Non-Goals**: what the design achieves and excludes
- **Decisions**: key technical choices with rationale and
alternatives considered
- **Risks / Trade-offs**: known limitations; format [Risk] -> Mitigation
- **Migration Plan**: deployment and rollback steps, if applicable
- **Open Questions**: outstanding unknowns
Focus on architecture and approach, not line-by-line implementation.
"""
[[artifacts]]
id = "decisions"
generates = "decisions/**/*.md"
target = "documentation/decisions"
description = "Architecture decision records (reserved; authoring workflow deferred)"
requires = ["proposal"]
instruction = """
Reserved namespace for architecture decision records. The ADR
authoring workflow is deferred to a later change; do not author
decision notes yet.
"""