Compare commits
4 Commits
983198b8b4
...
a3d35c7f12
| Author | SHA1 | Date | |
|---|---|---|---|
| a3d35c7f12 | |||
| def3d2cd6d | |||
| b7c173affa | |||
| 59d1054e1d |
@@ -1,9 +1,9 @@
|
|||||||
---
|
---
|
||||||
name: Fiona-Assistant Specification
|
name: Fiona-Assistant Specification
|
||||||
version: 1.22.1
|
version: 1.22.2
|
||||||
title: Project Spec Sheet
|
title: Project Spec Sheet
|
||||||
created: 2026-09-23
|
created: 2026-09-23
|
||||||
updated: 2026-10-24
|
updated: 2026-11-04
|
||||||
type: summary
|
type: summary
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -1812,9 +1812,9 @@ Requirements for the `wiki` subcommands.
|
|||||||
|
|
||||||
#### 7.1.1. wiki init
|
#### 7.1.1. wiki init
|
||||||
|
|
||||||
> Status: Partially Implemented
|
> Status: Implemented
|
||||||
|
|
||||||
Implements sections 3 and 4.7.1.
|
Implements sections 3, 4.7.1, and 7.1.1.
|
||||||
|
|
||||||
- *7.1.1.1.* Copy is 1:1 aside from `DATE_PLACEHOLDER`,
|
- *7.1.1.1.* Copy is 1:1 aside from `DATE_PLACEHOLDER`,
|
||||||
`ignore_files`, and paths matched by the repository `.gitignore`.
|
`ignore_files`, and paths matched by the repository `.gitignore`.
|
||||||
@@ -1832,8 +1832,8 @@ Implements sections 3 and 4.7.1.
|
|||||||
- *acceptance*: After init, `.gitignore` contains `__pycache__/`
|
- *acceptance*: After init, `.gitignore` contains `__pycache__/`
|
||||||
and `personal/`. A line `keep-me` written before init is still
|
and `personal/`. A line `keep-me` written before init is still
|
||||||
in the file.
|
in the file.
|
||||||
- *7.1.1.4.* `NOT_IMPLEMENTED` The CLI turns the refusal of *3.2.2.*
|
- *7.1.1.4.* The CLI turns the refusal of *3.2.2.* into one stderr
|
||||||
into one stderr line and exit 1 (*1.2.7.*):
|
line and exit 1 (*1.2.7.*):
|
||||||
`Error: Directory '<path>' already contains llm-wiki files:
|
`Error: Directory '<path>' already contains llm-wiki files:
|
||||||
<names>. Run fiona-assistant wiki update to refresh the template.`
|
<names>. Run fiona-assistant wiki update to refresh the template.`
|
||||||
The line is one line, even though it is wrapped here. `<names>` is
|
The line is one line, even though it is wrapped here. `<names>` is
|
||||||
|
|||||||
+10
-2
@@ -440,8 +440,16 @@ def main():
|
|||||||
sys.exit(1)
|
sys.exit(1)
|
||||||
elif args.command == "wiki":
|
elif args.command == "wiki":
|
||||||
if args.wiki_subcommand == "init":
|
if args.wiki_subcommand == "init":
|
||||||
result = wiki_init(args.directory)
|
try:
|
||||||
print(result)
|
result = wiki_init(args.directory)
|
||||||
|
print(result)
|
||||||
|
except FileExistsError as e:
|
||||||
|
# SPEC 7.1.1.4: format the error message and exit 1
|
||||||
|
# The FileExistsError message is: "Directory '<path>' already contains llm-wiki files: <names>"
|
||||||
|
# We want: "Error: Directory '<path>' already contains llm-wiki files: <names>. Run fiona-assistant wiki update to refresh the template."
|
||||||
|
formatted_error = f"Error: {e}. Run fiona-assistant wiki update to refresh the template."
|
||||||
|
print(formatted_error, file=sys.stderr)
|
||||||
|
sys.exit(1)
|
||||||
elif args.wiki_subcommand == "check-update":
|
elif args.wiki_subcommand == "check-update":
|
||||||
sys.exit(check_update_main(
|
sys.exit(check_update_main(
|
||||||
directory=args.directory,
|
directory=args.directory,
|
||||||
|
|||||||
@@ -0,0 +1,321 @@
|
|||||||
|
---
|
||||||
|
name: specification-writer
|
||||||
|
description: Load when writing or updating project specifications (SPEC.md).
|
||||||
|
Expert in creating structured and maintainable specification documents.
|
||||||
|
type: skill
|
||||||
|
version: 1.0.0
|
||||||
|
created: 2026-11-03
|
||||||
|
updated: 2026-11-03
|
||||||
|
---
|
||||||
|
|
||||||
|
# Specification Writer
|
||||||
|
|
||||||
|
You are an expert in writing software project specifications.
|
||||||
|
This skill provides guidance on creating structured, comprehensive, and
|
||||||
|
maintainable SPEC.md files following established best practices.
|
||||||
|
|
||||||
|
## When to Load
|
||||||
|
|
||||||
|
Load this skill when:
|
||||||
|
|
||||||
|
- Creating a new SPEC.md file for a project
|
||||||
|
- Updating or expanding an existing specification
|
||||||
|
- Reviewing specification structure and content
|
||||||
|
- Ensuring specifications follow consistent patterns
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
### Sectionize-Markdown Conventions
|
||||||
|
|
||||||
|
Always apply sectionize-markdown conventions to every SPEC.md file.
|
||||||
|
Reference: [sectionize-markdown skill](../sectionize-markdown/SKILL.md)
|
||||||
|
|
||||||
|
- Every heading MUST be numbered: `## 1.` for sections, `### 1.1`
|
||||||
|
for subsections, etc.
|
||||||
|
- Every list item MUST have a bold ID: `- **1.1.1** Text`
|
||||||
|
- TOC MUST be present under the title with markdown links
|
||||||
|
- Anchors MUST follow GitHub-style slugs
|
||||||
|
- Never renumber existing IDs - they may be cited elsewhere
|
||||||
|
|
||||||
|
## SPEC.md Structure Template
|
||||||
|
|
||||||
|
Use this structure as the foundation for all project specifications:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
---
|
||||||
|
name: <Project Name> Specification
|
||||||
|
version: <semver>
|
||||||
|
title: Project Spec Sheet
|
||||||
|
type: specification
|
||||||
|
created: <YYYY-MM-DD>
|
||||||
|
updated: <YYYY-MM-DD>
|
||||||
|
---
|
||||||
|
|
||||||
|
# <Project Name> Specification
|
||||||
|
|
||||||
|
<!-- toc-start: headings 2..6 -->
|
||||||
|
|
||||||
|
- [1. Product Overview](#1-product-overview)
|
||||||
|
- [1.1. Purpose](#11-purpose)
|
||||||
|
- [1.2. Scope](#12-scope)
|
||||||
|
- [1.3. Non-Goals](#13-non-goals)
|
||||||
|
- [1.4. Document Conventions](#14-document-conventions)
|
||||||
|
- [2. Architecture](#2-architecture)
|
||||||
|
- [2.1. Component Diagram](#21-component-diagram)
|
||||||
|
- [2.2. Data Flow](#22-data-flow)
|
||||||
|
- [2.3. Module Structure](#23-module-structure)
|
||||||
|
- [3. Core Contracts](#3-core-contracts)
|
||||||
|
- [3.1. Interfaces](#31-interfaces)
|
||||||
|
- [3.2. Data Structures](#32-data-structures)
|
||||||
|
- [4. Package and Runtime](#4-package-and-runtime)
|
||||||
|
- [4.1. Dependencies](#41-dependencies)
|
||||||
|
- [4.2. Entry Points](#42-entry-points)
|
||||||
|
- [4.3. Installation](#43-installation)
|
||||||
|
- [5. Feature Requirements](#5-feature-requirements)
|
||||||
|
- [6. Configuration Files](#6-configuration-files)
|
||||||
|
- [7. Error Handling](#7-error-handling)
|
||||||
|
- [8. Testing](#8-testing)
|
||||||
|
- [9. Deployment](#9-deployment)
|
||||||
|
|
||||||
|
<!-- toc-end -->
|
||||||
|
|
||||||
|
This document is the build contract for <Project Name>.
|
||||||
|
A reader with this file, and no source tree, must be able to produce
|
||||||
|
the same observable software.
|
||||||
|
Status values are `Implemented`, `Partially Implemented`, `Planned`,
|
||||||
|
and `Not Implemented`.
|
||||||
|
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
## Detailed Section Guidelines
|
||||||
|
|
||||||
|
### 1. Product Overview
|
||||||
|
|
||||||
|
#### 1.1. Purpose
|
||||||
|
|
||||||
|
- **1.1.1** Clearly state what problem the project solves
|
||||||
|
- **1.1.2** Describe the primary value proposition
|
||||||
|
- **1.1.3** Identify the target users or audience
|
||||||
|
- **1.1.4** Define the project's mission statement
|
||||||
|
|
||||||
|
#### 1.2. Scope
|
||||||
|
|
||||||
|
- **1.2.1** **In Scope**: List what the project will do
|
||||||
|
- **1.2.2** **Out of Scope**: List what the project will NOT do
|
||||||
|
- **1.2.3** Define clear boundaries for the project
|
||||||
|
|
||||||
|
#### 1.3. Non-Goals
|
||||||
|
|
||||||
|
- **1.3.1** Explicitly state what will not be implemented
|
||||||
|
- **1.3.2** Clarify boundaries with related projects or systems
|
||||||
|
- **1.3.3** Document conscious exclusions and rationale
|
||||||
|
|
||||||
|
#### 1.4. Document Conventions
|
||||||
|
|
||||||
|
- **1.4.1** Define terminology used throughout the document
|
||||||
|
- **1.4.2** Establish status labels and their meanings
|
||||||
|
- Implemented: Feature is complete and tested
|
||||||
|
- Partially Implemented: Feature is partially complete
|
||||||
|
- Planned: Feature is scheduled for implementation
|
||||||
|
- Not Implemented: Feature is specified but not yet built
|
||||||
|
- **1.4.3** Specify numbering conventions for sections and items
|
||||||
|
- **1.4.4** Define RFC2119 keywords (MUST, SHALL, SHOULD, MAY, etc.)
|
||||||
|
|
||||||
|
### 2. Architecture
|
||||||
|
|
||||||
|
#### 2.1. Component Diagram
|
||||||
|
|
||||||
|
- **2.1.1** Provide ASCII or Mermaid diagram showing system architecture
|
||||||
|
- **2.1.2** Label all major components and their relationships
|
||||||
|
- **2.1.3** Show data flow between components with arrows or descriptions
|
||||||
|
- **2.1.4** Indicate external dependencies and integrations
|
||||||
|
|
||||||
|
#### 2.2. Data Flow
|
||||||
|
|
||||||
|
- **2.2.1** Describe how data moves through the system end-to-end
|
||||||
|
- **2.2.2** Identify key data transformations at each stage
|
||||||
|
- **2.2.3** Note where data is persisted and in what format
|
||||||
|
- **2.2.4** Document data validation and error handling points
|
||||||
|
|
||||||
|
#### 2.3. Module Structure
|
||||||
|
|
||||||
|
- **2.3.1** Document the complete directory and file structure
|
||||||
|
- **2.3.2** Describe each module's responsibility and purpose
|
||||||
|
- **2.3.3** Note dependencies between modules
|
||||||
|
- **2.3.4** Indicate which modules are public vs internal APIs
|
||||||
|
|
||||||
|
### 3. Core Contracts
|
||||||
|
|
||||||
|
#### 3.1. Interfaces
|
||||||
|
|
||||||
|
- **3.1.1** Define purpose and role of each interface
|
||||||
|
- **3.1.2** List all required methods or functions with signatures
|
||||||
|
- **3.1.3** Document expected inputs, outputs, and return types
|
||||||
|
- **3.1.4** Specify error handling expectations and exceptions
|
||||||
|
- **3.1.5** Note version compatibility requirements
|
||||||
|
|
||||||
|
#### 3.2. Data Structures
|
||||||
|
|
||||||
|
- **3.2.1** Provide complete type definitions or JSON schemas
|
||||||
|
- **3.2.2** Include concrete examples of each data structure
|
||||||
|
- **3.2.3** Document validation rules and constraints
|
||||||
|
- **3.2.4** Note backward and forward compatibility considerations
|
||||||
|
- **3.2.5** Specify serialization formats (JSON, YAML, etc.)
|
||||||
|
|
||||||
|
### 4. Package and Runtime
|
||||||
|
|
||||||
|
#### 4.1. Dependencies
|
||||||
|
|
||||||
|
- **4.1.1** List runtime dependencies with exact version requirements
|
||||||
|
- **4.1.2** List development dependencies for building and testing
|
||||||
|
- **4.1.3** Document optional dependencies and their purposes
|
||||||
|
- **4.1.4** Note any version conflicts or compatibility constraints
|
||||||
|
|
||||||
|
#### 4.2. Entry Points
|
||||||
|
|
||||||
|
- **4.2.1** Define CLI entry points and their usage
|
||||||
|
- **4.2.2** Document library entry points for programmatic use
|
||||||
|
- **4.2.3** Specify plugin or extension entry points if applicable
|
||||||
|
- **4.2.4** Include examples of invoking each entry point
|
||||||
|
|
||||||
|
#### 4.3. Installation
|
||||||
|
|
||||||
|
- **4.3.1** Document all supported installation methods
|
||||||
|
- **4.3.2** Specify platform and environment requirements
|
||||||
|
- **4.3.3** Provide verification steps to confirm successful installation
|
||||||
|
- **4.3.4** Note any post-installation configuration needed
|
||||||
|
|
||||||
|
### 5. Feature Requirements
|
||||||
|
|
||||||
|
Organize requirements by feature area. Each feature section should include:
|
||||||
|
|
||||||
|
- **5.X.1** Status: One of Implemented, Partially Implemented, Planned,
|
||||||
|
Not Implemented
|
||||||
|
- **5.X.2** Purpose: User stories and motivations for the feature
|
||||||
|
- **5.X.3** Functional requirements: What the feature must do
|
||||||
|
- **5.X.4** Non-functional requirements: Performance, security, etc.
|
||||||
|
- **5.X.5** Acceptance criteria: How to verify the feature works
|
||||||
|
|
||||||
|
### 6. Configuration Files
|
||||||
|
|
||||||
|
For each configuration file, document:
|
||||||
|
|
||||||
|
- **6.1.1** Location: Both relative path and typical absolute paths
|
||||||
|
- Note platform-specific locations (Windows vs Unix)
|
||||||
|
- **6.1.2** Purpose: What the configuration controls
|
||||||
|
- **6.1.3** Structure: Complete format and schema
|
||||||
|
- **6.1.4** Default values: What settings are used if not specified
|
||||||
|
- **6.1.5** Customization: How users can modify the configuration
|
||||||
|
|
||||||
|
### 7. Error Handling
|
||||||
|
|
||||||
|
#### 7.1. Error Classification
|
||||||
|
|
||||||
|
- **7.1.1** Transient vs permanent errors
|
||||||
|
- **7.1.2** Recoverable vs unrecoverable errors
|
||||||
|
- **7.1.3** User-facing vs internal errors
|
||||||
|
- **7.1.4** Expected vs unexpected errors
|
||||||
|
|
||||||
|
#### 7.2. Error Reporting
|
||||||
|
|
||||||
|
- **7.2.1** Logging strategy and verbosity levels
|
||||||
|
- **7.2.2** User notification mechanisms (CLI, UI, etc.)
|
||||||
|
- **7.2.3** Error codes and their meanings
|
||||||
|
- **7.2.4** Error message format and content
|
||||||
|
|
||||||
|
#### 7.3. Recovery Strategies
|
||||||
|
|
||||||
|
- **7.3.1** Automatic recovery mechanisms and retries
|
||||||
|
- **7.3.2** Manual recovery procedures and user actions
|
||||||
|
- **7.3.3** Data consistency guarantees during failures
|
||||||
|
- **7.3.4** Rollback and undo capabilities
|
||||||
|
|
||||||
|
### 8. Testing
|
||||||
|
|
||||||
|
#### 8.1. Test Strategy
|
||||||
|
|
||||||
|
- **8.1.1** Testing pyramid: Unit, integration, system, E2E
|
||||||
|
- **8.1.2** Test coverage targets for different test types
|
||||||
|
- **8.1.3** Test environments and their configurations
|
||||||
|
- **8.1.4** CI/CD integration for automated testing
|
||||||
|
|
||||||
|
#### 8.2. Test Cases
|
||||||
|
|
||||||
|
- **8.2.1** Critical path tests covering core functionality
|
||||||
|
- **8.2.2** Edge case tests for boundary conditions
|
||||||
|
- **8.2.3** Regression tests for known issues
|
||||||
|
- **8.2.4** Performance and load tests if applicable
|
||||||
|
|
||||||
|
### 9. Deployment
|
||||||
|
|
||||||
|
#### 9.1. Release Process
|
||||||
|
|
||||||
|
- **9.1.1** Versioning scheme (SemVer, CalVer, etc.)
|
||||||
|
- **9.1.2** Release checklist and required steps
|
||||||
|
- **9.1.3** Rollback procedures for failed deployments
|
||||||
|
- **9.1.4** Release notes and changelog requirements
|
||||||
|
|
||||||
|
#### 9.2. Distribution
|
||||||
|
|
||||||
|
- **9.2.1** Package repositories and distribution channels
|
||||||
|
- **9.2.2** Installation methods for end users
|
||||||
|
- **9.2.3** Update mechanisms and version management
|
||||||
|
- **9.2.4** Offline or air-gapped installation options
|
||||||
|
|
||||||
|
## Sectionize-Markdown Integration
|
||||||
|
|
||||||
|
**CRITICAL**: Every SPEC.md file you create or modify MUST follow
|
||||||
|
sectionize-markdown conventions completely.
|
||||||
|
|
||||||
|
Before finalizing any SPEC.md:
|
||||||
|
|
||||||
|
1. Apply numbered headings (## 1., ### 1.1, #### 1.1.1)
|
||||||
|
2. Add bold IDs to all list items (- **1.1.1**)
|
||||||
|
3. Generate or update the TOC with markdown links
|
||||||
|
4. Ensure all anchors resolve correctly
|
||||||
|
5. Verify no duplicate IDs exist
|
||||||
|
|
||||||
|
Use the sectionize-markdown skill as the definitive reference for
|
||||||
|
all sectionizing conventions and requirements.
|
||||||
|
|
||||||
|
## Quality Checklist
|
||||||
|
|
||||||
|
Before marking a SPEC as complete, verify:
|
||||||
|
|
||||||
|
- [ ] **Structure**: All required sections are present
|
||||||
|
- [ ] **Numbering**: All headings and list items are numbered correctly
|
||||||
|
- [ ] **TOC**: Table of contents is present and accurate
|
||||||
|
- [ ] **Status**: Every feature section has a status line
|
||||||
|
- [ ] **Examples**: Code and configuration examples are provided
|
||||||
|
- [ ] **Cross-references**: All internal links resolve correctly
|
||||||
|
- [ ] **Consistency**: Terminology and formatting are consistent
|
||||||
|
- [ ] **Completeness**: All acceptance criteria are defined
|
||||||
|
- [ ] **Sectionized**: Follows sectionize-markdown conventions completely
|
||||||
|
|
||||||
|
## Maintenance Guidelines
|
||||||
|
|
||||||
|
- **Versioning**: Increment version in frontmatter with each update
|
||||||
|
- **Changelog**: Maintain updated and created dates in frontmatter
|
||||||
|
- **Review**: SPEC should be reviewed before major implementation
|
||||||
|
- **Sync**: Keep SPEC in sync with implementation (update status)
|
||||||
|
|
||||||
|
## Tools and Automation
|
||||||
|
|
||||||
|
When working with SPEC files:
|
||||||
|
|
||||||
|
- Use scripts to verify section numbering consistency
|
||||||
|
- Automate TOC generation to avoid manual errors
|
||||||
|
- Validate all internal links before committing
|
||||||
|
- Check for duplicate IDs across the entire document
|
||||||
|
- Run markdown linters to ensure formatting quality
|
||||||
|
|
||||||
|
## Common Pitfalls
|
||||||
|
|
||||||
|
- **Unnumbered items**: Every list item MUST have a bold ID
|
||||||
|
- **Broken anchors**: Always verify all TOC links resolve
|
||||||
|
- **Inconsistent status**: Use consistent status labels throughout
|
||||||
|
- **Missing examples**: Always include examples for data formats
|
||||||
|
- **Ambiguous requirements**: Requirements must be testable and verifiable
|
||||||
|
- **Overly verbose**: Be concise but comprehensive
|
||||||
|
- **Under-specified**: Include enough detail for implementation
|
||||||
@@ -194,6 +194,47 @@ class TestFionaMain:
|
|||||||
captured = capsys.readouterr()
|
captured = capsys.readouterr()
|
||||||
assert "Successfully initialized llm-wiki directory" in captured.out
|
assert "Successfully initialized llm-wiki directory" in captured.out
|
||||||
|
|
||||||
|
def test_main_wiki_init_duplicate_error(self, capsys, tmp_path):
|
||||||
|
"""Test main() wiki init on duplicate prints error on stderr and exits 1.
|
||||||
|
|
||||||
|
Implements SPEC 7.1.1.4: The CLI turns the refusal of 3.2.2 into
|
||||||
|
one stderr line and exit 1: Error: Directory '<path>' already contains
|
||||||
|
llm-wiki files: <names>. Run fiona-assistant wiki update to refresh
|
||||||
|
the template.
|
||||||
|
"""
|
||||||
|
from fiona.wiki.wiki import wiki_init
|
||||||
|
# Initialize the wiki first
|
||||||
|
wiki_init(str(tmp_path))
|
||||||
|
|
||||||
|
# Try to initialize again - should fail
|
||||||
|
with patch('sys.argv', ['fiona-assistant', 'wiki', 'init', str(tmp_path)]), \
|
||||||
|
pytest.raises(SystemExit) as exc_info:
|
||||||
|
main()
|
||||||
|
|
||||||
|
# Should exit with code 1
|
||||||
|
assert exc_info.value.code == 1
|
||||||
|
|
||||||
|
captured = capsys.readouterr()
|
||||||
|
# Should print error message to stderr
|
||||||
|
assert captured.err.startswith("Error: Directory '")
|
||||||
|
assert str(tmp_path) in captured.err
|
||||||
|
assert "already contains llm-wiki files:" in captured.err
|
||||||
|
# Should list the indicators
|
||||||
|
assert "AGENTS.md" in captured.err
|
||||||
|
assert "fiona-settings.json" in captured.err
|
||||||
|
assert "wiki/" in captured.err
|
||||||
|
assert "ingest/" in captured.err
|
||||||
|
assert "README.md" in captured.err
|
||||||
|
# Should include the suggestion
|
||||||
|
assert "Run fiona-assistant wiki update to refresh the template." in captured.err
|
||||||
|
# Should be exactly one line (may have trailing newline)
|
||||||
|
stripped_lines = [line for line in captured.err.split('\n') if line]
|
||||||
|
assert len(stripped_lines) == 1
|
||||||
|
# Should not print to stdout
|
||||||
|
assert captured.out == ""
|
||||||
|
# Should not print traceback
|
||||||
|
assert "Traceback" not in captured.err
|
||||||
|
|
||||||
def test_main_wiki_sanity(self, capsys, minimal_wiki):
|
def test_main_wiki_sanity(self, capsys, minimal_wiki):
|
||||||
"""Test main() dispatches wiki sanity and exits 0 on clean wiki."""
|
"""Test main() dispatches wiki sanity and exits 0 on clean wiki."""
|
||||||
with patch('sys.argv', ['fiona-assistant', 'wiki', 'sanity', str(minimal_wiki)]), \
|
with patch('sys.argv', ['fiona-assistant', 'wiki', 'sanity', str(minimal_wiki)]), \
|
||||||
|
|||||||
Reference in New Issue
Block a user