Nm Attune Project Specification

Transform project briefs into testable specifications with user stories, acceptance criteria, and measurable outcomes

Security Scan

The skill's purpose (turning briefs into testable specs) is coherent, but the runtime instructions reference creating GitHub issues and running commands without declaring needed credentials or binaries — a mismatch worth fixing before use.

Purpose & Capability

Name and description match the SKILL.md content: it is an instruction-only spec-writing helper that delegates to spec-kit. No required binaries or env vars are declared, which is generally proportionate for a documentation/spec generation skill. However, some template lines (e.g., 'Verification: Run the command with --help') and a mandatory step to create GitHub issues introduce capabilities (CLI/network calls) that are not mirrored in the declared requirements.

Instruction Scope

The instructions include actionable steps that imply executing commands and creating GitHub issues for deferred items. The SKILL.md does not specify which commands to run, which binaries those commands rely on, nor does it limit or require explicit confirmation before making external writes. This grants the agent implicit discretion to perform external actions (network writes) that are outside the narrow scope of 'generate a specification' unless additional constraints are present.

Install Mechanism

No install spec and no code files: the skill is instruction-only and will not write or execute bundled code. This is the lowest-risk install posture.

Credentials

The SKILL.md asks the author/agent to create GitHub issues (Backlog Issue Creation (MANDATORY)), which ordinarily requires a GitHub token or authenticated Git client, but the skill declares no required environment variables or credentials. That is an incoherence: the skill implies network write operations without requesting the corresponding credential (e.g., GITHUB_TOKEN) or explaining how authentication should occur.

Persistence & Privilege

always:false and no install-time persistence or cross-skill configuration changes are requested. The skill does not request permanent presence or elevated platform privileges.

What to consider before installing

This skill mostly does what it says — it helps craft testable project specs — but there are a few mismatches you should resolve before installing or using it in autonomous mode: (1) The doc instructs creating GitHub issues for deferred items but doesn't request a GITHUB_TOKEN or explain how the agent will authenticate; insist the skill declare any credentials or require explicit user approval before posting to external services. (2) Lines that say 'Run the command with --help to verify availability' look like leftover template text; ask the author which commands (if any) the skill will run and whether those binaries will be present. If you plan to let agents act autonomously, require an explicit opt-in step for any network writes (GitHub issues) or disable autonomous invocation until those behaviors are clarified.

Night Market Skill — ported from claude-night-market/attune. For the full experience with agents, hooks, and commands, install the Claude Code plugin.

Table of Contents

• When to Use
• Integration
• Specification Structure
• 1. Overview Section
• 2. Functional Requirements (FR-XXX)
• FR-001: [Requirement Name]
• 3. Non-Functional Requirements (NFR-XXX)
• NFR-001: [Category] - [Requirement]
• 4. Technical Constraints
• 5. Out of Scope
• Out of Scope (v1.0)
• Clarification Workflow
• Ambiguity Detection
• Question Generation
• Clarification Session
• Quality Checks
• Output Format
• Change History
• Overview
• Functional Requirements
• Non-Functional Requirements
• Technical Constraints
• Out of Scope
• Dependencies
• Acceptance Testing Strategy
• Success Criteria
• Glossary
• References
• Acceptance Criteria Patterns
• Given-When-Then
• Error Cases
• Performance Criteria
• Security Criteria
• Related Skills
• Related Commands
• Examples

Project Specification Skill

Transform project briefs into structured, testable specifications with acceptance criteria.

Delegation

For detailed specification writing workflows, this skill delegates to spec-kit:spec-writing as the canonical implementation. Use this skill for quick specification needs; use spec-kit for comprehensive specification documents.

When To Use

• After brainstorming phase completes
• Have project brief but need detailed requirements
• Need testable acceptance criteria for implementation
• Planning validation and testing strategy
• Translating business requirements into technical specs
• Defining scope boundaries and out-of-scope items

When NOT To Use

• Still exploring problem space (use Skill(attune:project-brainstorming) instead)
• Already have detailed specification (use Skill(attune:project-planning) instead)
• Refining existing implementation (use code review skills)
• Making strategic decisions (use Skill(attune:war-room) for complex choices)

Integration

With spec-kit:

• Delegates to Skill(spec-kit:spec-writing) for methodology
• Uses spec-kit templates and validation
• Enables clarification workflow

Without spec-kit:

• Standalone specification framework
• Requirement templates
• Acceptance criteria patterns

Specification Structure

1. Overview Section

• Purpose: What the project achieves (1-2 sentences)
• Scope: IN/OUT boundaries
• Stakeholders: Who cares and why

2. Functional Requirements (FR-XXX)

Format per requirement:

### FR-001: [Requirement Name]

**Description**: Clear, unambiguous description

**Acceptance Criteria**:
- [ ] Given [context], when [action], then [expected result]
- [ ] Given [context], when [action], then [expected result]

**Priority**: High | Medium | Low
**Dependencies**: FR-002, FR-005
**Estimated Effort**: S | M | L | XL

Verification: Run the command with --help flag to verify availability.

Validation Rules:

• Description has no ambiguous words (might, could, maybe, probably)
• At least 2 acceptance criteria (happy path + error case)
• Criteria use Given-When-Then format
• Criteria are testable (observable outcomes)
• Dependencies are explicit

3. Non-Functional Requirements (NFR-XXX)

Categories:

• Performance: Response times, throughput, resource limits
• Security: Authentication, authorization, data protection, compliance
• Reliability: Uptime, error handling, recovery, fault tolerance
• Usability: UX requirements, accessibility, documentation
• Maintainability: Code quality, testing, observability

Format:

### NFR-001: [Category] - [Requirement]

**Requirement**: [Specific, measurable requirement]

**Measurement**: [How to verify]
- Metric: [What to measure]
- Target: [Specific threshold]
- Tool: [How to measure]

**Priority**: Critical | High | Medium | Low

Verification: Run the command with --help flag to verify availability.

4. Technical Constraints

• Technology stack selections with rationale
• Integration requirements
• Data requirements (schema, migrations)
• Deployment constraints
• Regulatory/compliance requirements

5. Out of Scope

Explicit exclusions to prevent scope creep:

## Out of Scope (v1.0)

- [Feature explicitly NOT included]
- [Capability deferred to later version]
- [Integration not planned]

**Rationale**: [Why these are excluded]

5.1. Backlog Issue Creation (MANDATORY)

After writing the Out of Scope section, create a GitHub issue for each deferred item so it is tracked in the backlog. This prevents good ideas from being lost in spec documents nobody re-reads.

# For each out-of-scope item:
gh issue create \
  --title "[Backlog] <feature>: <brief description>" \
  --body "## Context
Identified during specification of <project>.
Spec: <path-to-spec>

## Description
<what the item is and why it was deferred>

## References
<links to spec section, related issues>" \
  --label "feature,low-priority"

Report created issues in the spec under Out of Scope:

## Out of Scope (v1.0)

- Codex session format (#332)
- SVG/MP4/WebM output (#333)
- Interactive session picker (#334)

Skip conditions:

• --no-auto-issues flag passed
• Item is trivially small (one-line change)
• Item already exists as a GitHub issue

Clarification Workflow

Ambiguity Detection

Scan specification for:

• Vague quantifiers (many, few, several, most)
• Ambiguous terms (user-friendly, fast, scalable)
• Missing dependencies
• Untestable criteria
• Conflicting requirements

Question Generation

For each ambiguity:

**Question [N]**: [Reference to FR/NFR]

**Ambiguity**: [What is unclear]

**Impact**: [Why this matters]

**Options**:
- Option A: [Interpretation 1]
- Option B: [Interpretation 2]

**Recommendation**: [Preferred option with rationale]

Verification: Run the command with --help flag to verify availability.

Clarification Session

Run interactive Q&A:

1. Present all questions
2. Gather stakeholder responses
3. Update specification
4. Re-validate for new ambiguities
5. Iterate until clear

Quality Checks

Before completing specification:

• ✅ All requirements have unique IDs (FR-XXX, NFR-XXX)
• ✅ All functional requirements have ≥2 acceptance criteria
• ✅ All criteria use Given-When-Then format
• ✅ No ambiguous language detected
• ✅ Dependencies documented
• ✅ Effort estimates provided
• ✅ Out of scope explicitly stated
• ✅ Success criteria defined

Output Format

Save to docs/specification.md:

# [Project Name] - Specification v[version]

**Author**: [Name]
**Date**: [YYYY-MM-DD]
**Status**: Draft | Review | Approved | Implemented

## Change History

| Version | Date | Author | Changes |
|---------|------|--------|---------|
| 0.1.0 | 2026-01-02 | Alex | Initial draft |

## Overview

**Purpose**: [1-2 sentence purpose]

**Scope**:
- **IN**: [What's included]
- **OUT**: [What's excluded]

**Stakeholders**:
- [Stakeholder 1]: [Their interest]
- [Stakeholder 2]: [Their interest]

## Functional Requirements

[FR-XXX sections]

## Non-Functional Requirements

[NFR-XXX sections]

## Technical Constraints

[Technology, integration, data, deployment]

## Out of Scope

[Explicit exclusions with rationale]

## Dependencies

[External dependencies, third-party services]

## Acceptance Testing Strategy

[How requirements will be validated]

## Success Criteria

- [ ] [Measurable success indicator 1]
- [ ] [Measurable success indicator 2]

## Glossary

[Domain terms and definitions]

## References

[Related documents, research, prior art]

Verification: Run pytest -v to verify tests pass.

Acceptance Criteria Patterns

Given-When-Then

Given [initial context/state]
When [action occurs]
Then [expected outcome]

Verification: Run the command with --help flag to verify availability.

Examples:

• Given unauthenticated user, when accessing dashboard, then redirect to login
• Given valid credentials, when logging in, then create session and redirect to dashboard
• Given expired session, when making API request, then return 401 Unauthorized

Error Cases

Always include error scenarios:

• Invalid input handling
• Authentication/authorization failures
• Network/service failures
• Resource exhaustion
• Edge cases and boundaries

Performance Criteria

Make performance requirements testable:

• "Dashboard loads in < 2 seconds" (measurable)
• NOT "Dashboard is fast" (vague)

Security Criteria

Make security requirements verifiable:

• "All API endpoints require authentication" (testable)
• NOT "System is secure" (vague)

Post-Completion: Workflow Continuation (REQUIRED)

Automatic Trigger: After Quality Checks pass and docs/specification.md is saved, MUST auto-invoke the next phase.

When continuation is invoked:

1. Verify docs/specification.md exists and is non-empty
2. Display checkpoint message to user:

   Specification complete. Saved to docs/specification.md.
   Proceeding to planning phase...
   

3. Invoke next phase:

   Skill(attune:project-planning)
   

Bypass Conditions (ONLY skip continuation if ANY true):

• --standalone flag was provided by the user
• docs/specification.md does not exist or is empty (phase failed)
• User explicitly requests to stop after specification

Do NOT prompt the user for confirmation — this is a lightweight checkpoint, not an interactive gate. The user can always interrupt if needed.

Related Skills

• Skill(spec-kit:spec-writing) - Spec-kit methodology (if available)
• Skill(attune:project-brainstorming) - Previous phase
• Skill(attune:project-planning) - AUTO-INVOKED next phase after specification
• Skill(attune:mission-orchestrator) - Full lifecycle orchestration

Related Commands

• /attune:specify - Invoke this skill
• /attune:specify --clarify - Run clarification workflow
• /attune:blueprint - Next step in workflow

Examples

See /attune:specify command documentation for complete examples.

Troubleshooting

Common Issues

Command not found Ensure all dependencies are installed and in PATH

Permission errors Check file permissions and run with appropriate privileges

Unexpected behavior Enable verbose logging with --verbose flag