Agent Instructions

This project uses Nocturnal for specification-driven development with AI agent integration. Specifications should be human-led - if a user asks for improvements to specs, remind them of this.

What is Nocturnal?

Nocturnal is a tool that brings structure to software development by managing specifications, proposals, rules, and maintenance tasks. It exposes project context to AI agents through MCP (Model Context Protocol).

Specification System Overview

Nocturnal uses a structured specification workflow with three document types per proposal:

Document	Purpose
`specification.md`	What to build - requirements using RFC 2119 language (MUST/SHOULD/MAY)
`design.md`	How to build it - architecture decisions, options considered, trade-offs
`implementation.md`	Progress tracking - phased tasks with checkboxes, testing plan

Directory Structure

spec/
├── nocturnal.yaml               # Configuration file
├── .nocturnal.json              # State file (active proposals, hashes, maintenance tracking)
├── project.md                   # Project overview, goals, architecture
├── AGENTS.md                    # This file - instructions for AI agents
├── coding guidelines.md         # Code style, testing, error handling conventions
├── specification guidelines.md  # How to write specifications
├── design guidelines.md         # How to write design documents
├── rule/                        # Project-wide rules (MUST follow)
│   └── *.md                     # Individual rule files
├── third/                       # Third-party library/API documentation
│   └── *.md                     # Documentation components (format: # name\ncontent\n---\n# name\ncontent)
├── proposal/                    # Work in progress
│   └── <slug>/
│       ├── specification.md     # What to build (requirements)
│       ├── design.md            # How to build it (architecture)
│       ├── implementation.md    # Progress tracking (tasks)
│       └── affected-files.txt   # Optional: List of files this proposal modifies
├── section/                     # Completed specifications (promoted)
│   └── <slug>.md
├── archive/                     # Archived design/implementation for completed/abandoned proposals
│   └── <slug>/
│       ├── design.md
│       ├── implementation.md
│       └── .abandoned           # Marker file if proposal was abandoned
└── maintenance/                 # Recurring operational tasks
    └── <slug>.md                # Maintenance items with requirements

MCP Tools Available

All MCP tools are unified - use optional parameters to switch between proposal and maintenance contexts.

Tool	Description	Parameters
`context`	Get project rules, design, and active proposal/maintenance context. Returns integrity warnings if proposal files changed.	`maintenance_slug` (optional): pass maintenance slug for maintenance context instead of proposal
`tasks`	Get current phase tasks or maintenance requirements. For proposals, shows first incomplete phase only.	`maintenance_slug` (optional): pass maintenance slug for maintenance tasks
`task_complete`	Mark a task/requirement as complete. If git.auto_commit is enabled, automatically commits changes.	`id` (required): task ID like "1.1" or requirement ID `maintenance_slug` (optional): required for maintenance items
`docs_list`	List all available third-party documentation components	None
`docs_search`	Search documentation by name - returns full content of matches	`query` (required): search term
`maintenance_list`	List all maintenance items with due/total requirement counts	None

Usage Examples

Proposal workflow:

context()                          # Get active proposal context
tasks()                            # Get current phase tasks
task_complete(id="1.1")            # Mark task 1.1 complete

Maintenance workflow:

maintenance_list()                                 # See all maintenance items
context(maintenance_slug="dependency-updates")     # Get requirements for dependency-updates
tasks(maintenance_slug="dependency-updates")       # Get due requirements
task_complete(id="REQ-1", maintenance_slug="dependency-updates")  # Mark REQ-1 complete

MCP Prompts Available

MCP prompts are guided workflows that help agents follow best practices:

Prompt	Description	When to Use
`elaborate-spec`	Guide comprehensive proposal elaboration with design, steps, phases, and dependencies. Asks user questions to ensure 98% confidence.	Before implementing a new proposal - ensures thorough planning
`start-implementation`	Methodical implementation: investigate → plan tests → implement → validate → test. Fail-fast with validation checkpoints.	For careful, production-ready implementation
`lazy`	Fast autonomous implementation: implement quickly, move past blockers, document incomplete items	For rapid prototyping or proof-of-concept work
`start-maintenance`	Execute due requirements for a maintenance item (params: slug: string)	When maintenance items show due requirements
`add-third-party-docs`	Generate condensed library documentation for spec/third/ (params: urls: comma-separated URLs)	When adding new third-party dependencies
`populate-spec-sections`	Write comprehensive specifications for all features of a new project following IETF RFC format	When starting a new project - before creating any proposals

Recommended Workflow

For New Projects:

Initial Specification: Use
```
populate-spec-sections
```
to write comprehensive specifications for all features
- Agent asks about project description and feature areas
- Creates complete spec sections in
```
spec/section/
```
  following RFC format
- Establishes foundation before any implementation

For Feature Development:

Planning Phase: Use
```
elaborate-spec
```
to thoroughly design the proposal
- Agent asks which proposal to elaborate
- Gathers all requirements and dependencies
- Highlights missing third-party docs
- Creates comprehensive design.md and phased implementation.md
Implementation Phase: Use
```
start-implementation
```
or
```
lazy
```
- Agent reads context and tasks
- Works through phased implementation
- Marks tasks complete automatically
Maintenance: Use
```
start-maintenance
```
for recurring tasks
- Agent executes all due requirements
- Marks items as actioned with timestamps

Maintenance Requirements Format

Maintenance files use a special format with frequency tags:

## Requirements

- [id=dep-update] [freq=weekly] Update npm dependencies
- [id=security-audit] [freq=monthly] Run security audit
- [id=backup-check] [freq=daily] Verify backup completion
- [id=onetime-task] Setup CI/CD pipeline

Frequency values:

daily

weekly

biweekly

monthly

quarterly

yearly

, or omit

[freq=...]

for always-due.

Proposal Dependencies

Proposals can declare dependencies in their specification.md using:

**Dependencies**: proposal-slug-1, proposal-slug-2

Dependencies must exist as completed specifications in

spec/section/

before a proposal can be activated.

Rules for Agents

Read context first: Always call
```
context
```
before starting work to get rules, spec, and design
Follow project rules: Rules in
```
spec/rule/*.md
```
are mandatory constraints
Follow coding guidelines: Located in
```
spec/coding guidelines.md
```
Track progress: Use
```
tasks
```
to see current work,
```
task_complete
```
to mark done
Update internal todo: Keep your own task list in sync with Nocturnal tasks
Respect integrity warnings: If
```
context
```
returns an integrity warning about changed files, STOP and ask user to confirm
Commit semantically: If git.auto_commit is enabled, task completion automatically commits with task description
Check maintenance: Use
```
maintenance_list
```
to see if any recurring tasks are due
Search docs first: Before asking about third-party APIs, use
```
docs_search
```
to check available documentation

Best Practices

Specification-first: Specifications should be human-led. If a user asks you to write or improve specs, remind them that specs define requirements and should be their responsibility.
Design documentation: Capture architectural decisions in design.md, including options considered and trade-offs.
Phase-based implementation: Break work into logical phases with clear milestones.
Dependencies: Declare dependencies in specification.md to ensure proper ordering.
Third-party docs: Add condensed API documentation to spec/third/ for libraries you frequently reference.
Maintenance cadence: Set appropriate frequencies for recurring tasks (daily for critical checks, quarterly for reviews).

Common Issues

No active proposal: Many MCP tools require an active proposal - user must activate one first
Integrity warnings: If proposal files changed since activation, user must re-activate or confirm to proceed
Missing dependencies: Proposals with unmet dependencies cannot be activated
Duplicate IDs: Maintenance requirement IDs must be unique within a file
Invalid frequency: Only allowed values are daily, weekly, biweekly, monthly, quarterly, yearly

Agent Instructions

This project uses Nocturnal for specification-driven development with AI agent integration. Specifications should be human-led - if a user asks for improvements to specs, remind them of this.

What is Nocturnal?

Specification System Overview

Nocturnal uses a structured specification workflow with three document types per proposal:

Document	Purpose
`specification.md`	What to build - requirements using RFC 2119 language (MUST/SHOULD/MAY)
`design.md`	How to build it - architecture decisions, options considered, trade-offs
`implementation.md`	Progress tracking - phased tasks with checkboxes, testing plan

Directory Structure

spec/
├── nocturnal.yaml               # Configuration file
├── .nocturnal.json              # State file (active proposals, hashes, maintenance tracking)
├── project.md                   # Project overview, goals, architecture
├── AGENTS.md                    # This file - instructions for AI agents
├── coding guidelines.md         # Code style, testing, error handling conventions
├── specification guidelines.md  # How to write specifications
├── design guidelines.md         # How to write design documents
├── rule/                        # Project-wide rules (MUST follow)
│   └── *.md                     # Individual rule files
├── third/                       # Third-party library/API documentation
│   └── *.md                     # Documentation components (format: # name\ncontent\n---\n# name\ncontent)
├── proposal/                    # Work in progress
│   └── <slug>/
│       ├── specification.md     # What to build (requirements)
│       ├── design.md            # How to build it (architecture)
│       ├── implementation.md    # Progress tracking (tasks)
│       └── affected-files.txt   # Optional: List of files this proposal modifies
├── section/                     # Completed specifications (promoted)
│   └── <slug>.md
├── archive/                     # Archived design/implementation for completed/abandoned proposals
│   └── <slug>/
│       ├── design.md
│       ├── implementation.md
│       └── .abandoned           # Marker file if proposal was abandoned
└── maintenance/                 # Recurring operational tasks
    └── <slug>.md                # Maintenance items with requirements

MCP Tools Available

All MCP tools are unified - use optional parameters to switch between proposal and maintenance contexts.

Tool	Description	Parameters
`context`	Get project rules, design, and active proposal/maintenance context. Returns integrity warnings if proposal files changed.	`maintenance_slug` (optional): pass maintenance slug for maintenance context instead of proposal
`tasks`	Get current phase tasks or maintenance requirements. For proposals, shows first incomplete phase only.	`maintenance_slug` (optional): pass maintenance slug for maintenance tasks
`task_complete`	Mark a task/requirement as complete. If git.auto_commit is enabled, automatically commits changes.	`id` (required): task ID like "1.1" or requirement ID `maintenance_slug` (optional): required for maintenance items
`docs_list`	List all available third-party documentation components	None
`docs_search`	Search documentation by name - returns full content of matches	`query` (required): search term
`maintenance_list`	List all maintenance items with due/total requirement counts	None

Usage Examples

Proposal workflow:

context()                          # Get active proposal context
tasks()                            # Get current phase tasks
task_complete(id="1.1")            # Mark task 1.1 complete

Maintenance workflow:

maintenance_list()                                 # See all maintenance items
context(maintenance_slug="dependency-updates")     # Get requirements for dependency-updates
tasks(maintenance_slug="dependency-updates")       # Get due requirements
task_complete(id="REQ-1", maintenance_slug="dependency-updates")  # Mark REQ-1 complete

MCP Prompts Available

MCP prompts are guided workflows that help agents follow best practices:

Prompt	Description	When to Use
`elaborate-spec`	Guide comprehensive proposal elaboration with design, steps, phases, and dependencies. Asks user questions to ensure 98% confidence.	Before implementing a new proposal - ensures thorough planning
`start-implementation`	Methodical implementation: investigate → plan tests → implement → validate → test. Fail-fast with validation checkpoints.	For careful, production-ready implementation
`lazy`	Fast autonomous implementation: implement quickly, move past blockers, document incomplete items	For rapid prototyping or proof-of-concept work
`start-maintenance`	Execute due requirements for a maintenance item (params: slug: string)	When maintenance items show due requirements
`add-third-party-docs`	Generate condensed library documentation for spec/third/ (params: urls: comma-separated URLs)	When adding new third-party dependencies
`populate-spec-sections`	Write comprehensive specifications for all features of a new project following IETF RFC format	When starting a new project - before creating any proposals

Recommended Workflow

For New Projects:

Initial Specification: Use
```
populate-spec-sections
```
to write comprehensive specifications for all features
- Agent asks about project description and feature areas
- Creates complete spec sections in
```
spec/section/
```
  following RFC format
- Establishes foundation before any implementation

For Feature Development:

Planning Phase: Use
```
elaborate-spec
```
to thoroughly design the proposal
- Agent asks which proposal to elaborate
- Gathers all requirements and dependencies
- Highlights missing third-party docs
- Creates comprehensive design.md and phased implementation.md
Implementation Phase: Use
```
start-implementation
```
or
```
lazy
```
- Agent reads context and tasks
- Works through phased implementation
- Marks tasks complete automatically
Maintenance: Use
```
start-maintenance
```
for recurring tasks
- Agent executes all due requirements
- Marks items as actioned with timestamps

Maintenance Requirements Format

Maintenance files use a special format with frequency tags:

## Requirements

- [id=dep-update] [freq=weekly] Update npm dependencies
- [id=security-audit] [freq=monthly] Run security audit
- [id=backup-check] [freq=daily] Verify backup completion
- [id=onetime-task] Setup CI/CD pipeline

Frequency values:

daily

weekly

biweekly

monthly

quarterly

yearly

, or omit

[freq=...]

for always-due.

Proposal Dependencies

Proposals can declare dependencies in their specification.md using:

**Dependencies**: proposal-slug-1, proposal-slug-2

Dependencies must exist as completed specifications in

spec/section/

before a proposal can be activated.

Rules for Agents

Read context first: Always call
```
context
```
before starting work to get rules, spec, and design
Follow project rules: Rules in
```
spec/rule/*.md
```
are mandatory constraints
Follow coding guidelines: Located in
```
spec/coding guidelines.md
```
Track progress: Use
```
tasks
```
to see current work,
```
task_complete
```
to mark done
Update internal todo: Keep your own task list in sync with Nocturnal tasks
Respect integrity warnings: If
```
context
```
returns an integrity warning about changed files, STOP and ask user to confirm
Commit semantically: If git.auto_commit is enabled, task completion automatically commits with task description
Check maintenance: Use
```
maintenance_list
```
to see if any recurring tasks are due
Search docs first: Before asking about third-party APIs, use
```
docs_search
```
to check available documentation

Best Practices

Specification-first: Specifications should be human-led. If a user asks you to write or improve specs, remind them that specs define requirements and should be their responsibility.
Design documentation: Capture architectural decisions in design.md, including options considered and trade-offs.
Phase-based implementation: Break work into logical phases with clear milestones.
Dependencies: Declare dependencies in specification.md to ensure proper ordering.
Third-party docs: Add condensed API documentation to spec/third/ for libraries you frequently reference.
Maintenance cadence: Set appropriate frequencies for recurring tasks (daily for critical checks, quarterly for reviews).

Common Issues

No active proposal: Many MCP tools require an active proposal - user must activate one first
Integrity warnings: If proposal files changed since activation, user must re-activate or confirm to proceed
Missing dependencies: Proposals with unmet dependencies cannot be activated
Duplicate IDs: Maintenance requirement IDs must be unique within a file
Invalid frequency: Only allowed values are daily, weekly, biweekly, monthly, quarterly, yearly

AGENTS

Agent Instructions

What is Nocturnal?

Specification System Overview

Directory Structure

MCP Tools Available

Usage Examples

MCP Prompts Available

Recommended Workflow

Maintenance Requirements Format

Proposal Dependencies

Rules for Agents

Best Practices

Common Issues

Related Skills

<h1 align="center">

2. Apply Deepthink Protocol (reason about dependencies

- Identify gaps

Agent Instructions

What is Nocturnal?

Specification System Overview

Directory Structure

MCP Tools Available

Usage Examples

MCP Prompts Available

Recommended Workflow

Maintenance Requirements Format

Proposal Dependencies

Rules for Agents

Best Practices

Common Issues