Compare commits

..

4 Commits

Author SHA1 Message Date
nvaldez a3d35c7f12 Implement SPEC 7.1.1.4: wiki init duplicate error handling
wiki init now catches FileExistsError, prints one stderr line with the
update suggestion, and exits 1. SPEC.md status for wiki init bumped to
Implemented (v1.22.2). Adds test for message format, exit code, and
single-line stderr output.

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-19 11:53:41 +01:00
nvaldez def3d2cd6d Rewrite specification-writer skill to be self-contained
- Remove references to fiona-assistant and agent-cost-estimator
- Include all SPEC structure details directly in the skill
- Add comprehensive section guidelines with numbered items
- Expand core contracts, configuration files, error handling sections
- Maintain sectionize-markdown integration
- All housekeeping checks pass

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-03 16:34:25 +01:00
nvaldez b7c173affa Fix linting violations in specification-writer skill
- Fix MD013 line length violations by splitting long lines
- Fix MD032 by adding blank lines around lists
- Fix MD036 by removing bold emphasis used as headings
- All housekeeping checks now pass

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-03 16:30:57 +01:00
nvaldez 59d1054e1d Add specification-writer skill for expert SPEC.md creation
- Create new skill at src/fiona/data/llm_wiki/utils/skills/specification-writer/
- Provides comprehensive guidance for writing project specifications
- Integrates with sectionize-markdown skill for consistent formatting
- Includes structure template based on fiona-assistant and agent-cost-estimator patterns
- Emphasizes always sectionizing SPEC files with numbered headings and list items
- Features quality checklist and maintenance guidelines

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
2026-11-03 16:27:05 +01:00
4 changed files with 378 additions and 8 deletions
+6 -6
View File
@@ -1,9 +1,9 @@
---
name: Fiona-Assistant Specification
version: 1.22.1
version: 1.22.2
title: Project Spec Sheet
created: 2026-09-23
updated: 2026-10-24
updated: 2026-11-04
type: summary
---
@@ -1812,9 +1812,9 @@ Requirements for the `wiki` subcommands.
#### 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`,
`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__/`
and `personal/`. A line `keep-me` written before init is still
in the file.
- *7.1.1.4.* `NOT_IMPLEMENTED` The CLI turns the refusal of *3.2.2.*
into one stderr line and exit 1 (*1.2.7.*):
- *7.1.1.4.* The CLI turns the refusal of *3.2.2.* into one stderr
line and exit 1 (*1.2.7.*):
`Error: Directory '<path>' already contains llm-wiki files:
<names>. Run fiona-assistant wiki update to refresh the template.`
The line is one line, even though it is wrapped here. `<names>` is
+10 -2
View File
@@ -440,8 +440,16 @@ def main():
sys.exit(1)
elif args.command == "wiki":
if args.wiki_subcommand == "init":
result = wiki_init(args.directory)
print(result)
try:
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":
sys.exit(check_update_main(
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
+41
View File
@@ -194,6 +194,47 @@ class TestFionaMain:
captured = capsys.readouterr()
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):
"""Test main() dispatches wiki sanity and exits 0 on clean wiki."""
with patch('sys.argv', ['fiona-assistant', 'wiki', 'sanity', str(minimal_wiki)]), \