diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..731705d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,81 @@ +# AGENTS.md + +## Overview + +Specture is a spec-driven software architecture system designed for small teams working with AI agents. It provides a lightweight, document-driven approach to project planning where specs are markdown files in the `specs/` directory. + +**For detailed information about the Specture System, see `specs/README.md`.** + +## Directory Structure + +- **`specs/`**: Markdown spec files for planned changes (features, refactors, improvements) +- **`specs/README.md`**: Complete spec guidelines, workflow, and best practices +- **`AGENTS.md`**: This file, for agentic coding tools + +## Core Concepts + +### What Are Specs? + +Specs are design documents describing planned changes: new features, major refactors, redesigns, and tooling improvements. They are inspired by PEP (Python Enhancement Proposal) and BIP (Bitcoin Improvement Proposal) systems. + +- **NOT for bugs**: Use the issue tracker for bugs (cases where software doesn't match spec descriptions) +- **Scope**: Can range from large (traditional epic size) to small (minor UI improvements) +- **Coherent units**: Split specs for independent changes; combine for shared design decisions + +### Spec Structure + +All specs follow this format: + +1. **YAML Frontmatter**: Metadata (status, author, dates) +2. **Title (H1)**: Clear, descriptive name +3. **Description**: Overview of what's being proposed, why, and the problem it solves +4. **Design Decisions** (optional): Rationale for major design choices +5. **Task List**: Detailed, actionable implementation tasks grouped into sections + +### Spec Lifecycle + +Each spec has a status field that tracks its state: + +- **`draft`**: Being written and refined +- **`approved`**: Ready for implementation +- **`in-progress`**: Implementation underway +- **`completed`**: All tasks finished +- **`rejected`**: Reviewed but not approved + +### File Naming + +Use kebab-case filenames with numeric prefix: + +- `000-mvp.md` +- `001-add-authentication-system.md` +- `013-refactor-database-layer.md` + +### Precedence System + +Higher-numbered specs take precedence over lower-numbered specs. If two specs conflict, the higher number wins. This avoids the need to retroactively update completed specs. + +### Workflow Guidelines + +1. **Check spec status** before starting work—only implement specs marked `approved` or `in-progress` +2. **Update task lists** as you complete tasks in a spec +3. **Don't update completed specs** (except for typos/factual corrections)—create a new spec if requirements change +4. **Document your work** in the task list; the spec becomes the historical record +5. **Refer to design decisions** in the spec when making implementation choices + +See `specs/README.md` for detailed guidelines on spec workflow, best practices, and design decision documentation. + +## Build/Test Commands + +No build or test commands yet—project is in early stages. Implementation will be in Go. + +## Code Style (When Implementation Begins) + +- **Language**: Go +- **Naming**: Kebab-case with numeric prefix for specs and files +- **Documentation**: Prioritize clarity; explain "why" in specs; code shows "how" + +## CLI Tools (To Be Implemented) + +- `specture setup`: Initialize Specture in a repo +- `specture new`: Create new spec with template +- `specture validate`: Validate spec files diff --git a/specs/000-setup-cli.md b/specs/000-setup-cli.md index 48f64c2..c9ce4ab 100644 --- a/specs/000-setup-cli.md +++ b/specs/000-setup-cli.md @@ -1,24 +1,92 @@ -# Implement Setup CLI +--- +status: draft +author: Addison Emig +creation_date: 2025-12-18 +--- -## Description +# Implement Basic CLI -Implement a basic CLI tool to make it convenient to add the Specture System to any git repository. The CLI will be written in Go and prompt the user for configuration options like git forge. +Implement a basic CLI that makes it convenient to use the Specture System in any repoistory. -This tool will streamline the onboarding process for teams wanting to adopt the Specture System, automating the creation of necessary directories, documentation, and configuration files. The CLI will set up: +## Tools + +### Setup Project + +`specture setup` + +Alias: `update` + +This makes it easy to add the Specture System to any git repository. + +The tool will exit early if it doesn't detect a git repository in the current directory, or if the repository has uncommitted changes. Users will be prompted to verify the generated changes before committing. The tool will _not_ automatically commit. + +The tool looks at the git remotes to determine which forge they are using. If there are no remotes, prompt the user to find out which forge. + +- If they are using GitLab, the generated files should refer to "merge requests" +- Otherwise, the generated files should refer to "pull requests" + +Things that will be generated: - `specs/` directory for spec files - `specs/README.md` with the spec guidelines -- `AGENTS.md` file (adding a Specture System section without overwriting existing content) -The CLI will exit early if it doesn't detect a git repository in the current directory, or if the repository has uncommitted changes. Users will be able to disable individual changes they don't want, and will always be prompted to verify the proposed changes before committing. This interactive approach ensures users maintain full control over what gets added to their repository while reducing manual setup effort. +The tool should automatically detect if the repo has the following files: + +- `AGENTS.md` +- `CLAUDE.md` + +For each file, the CLI should prompt the user if they want to update that file. If yes, then the CLI should give them a prompt to copy and paste into their agent. The prompt will be something to the effect of "This project uses the Specture System. Read specs/README.md to learn about the system, then update AGENTS.md with basic information for agents. The agents should reference the file when they need more information about the system." A `--dry-run` flag will allow users to preview all changes without modifying any files or creating commits. This mode will be particularly useful for automated testing within Specture itself, ensuring the CLI behaves correctly across different repository configurations. -The CLI will be defensive against accidentally overwriting existing spec files, protecting user-created specifications. However, it will freely replace `specs/README.md` to ensure repositories stay up-to-date as the Specture System evolves. The CLI will support updating repositories that already have the Specture System installed, making it easy to pull in the latest guidelines and improvements. +The tool will be defensive against accidentally overwriting existing spec files, protecting user-created specifications. However, it will freely replace `specs/README.md` to ensure repositories stay up-to-date as the Specture System evolves. + +Users can run the tool in repos that already have the Specture System installed to pull in the latest guidelines and improvements. + +### New Spec + +`specture new` + +alias: `n` + +This makes it easy to add new specs. + +It should automate all the following: + +- Create branch +- Create file based on basic template +- Open file in user's editor + +### Validate Spec + +`specture validate` + +alias: `v` + +This makes it easy to validate specs to make sure they follow the Specture System. + +It should check the following: + +- Valid frontmatter + - Valid status +- Valid description +- Valid task list + +It should be possible to validate one specific spec or all the specs. ## Design Decisions -TBD +### Programming Language + +- Chosen: go + - Easy to build standalone binary + - Good CLI tooling + - Fast +- Considered: bash + - Designed for scripting + - Hard to maintain + - Hard to implement complex features + - Slow ## Task List diff --git a/specs/001-project-specific-approval-rules.md b/specs/001-project-specific-approval-rules.md new file mode 100644 index 0000000..a55a0f7 --- /dev/null +++ b/specs/001-project-specific-approval-rules.md @@ -0,0 +1,13 @@ +--- +status: draft +author: Addison Emig +creation_date: 2025-12-18 +--- + +# Project-Specific Approval Rules Integration + +Currently, the Specture System states that approval criteria are project-specific but provides no mechanism for projects to formally define or enforce their own approval rules. + +We need to come up with some mechanism for allowing projects to document their project-specific approval rules. + +See [this thread](https://github.com/mrs-electronics-inc/android-automotive/pull/2#discussion_r2632381243) for some ideas. diff --git a/specs/README.md b/specs/README.md index db93cc7..24a9574 100644 --- a/specs/README.md +++ b/specs/README.md @@ -1,178 +1,186 @@ # Spec Guidelines -> This project uses the [Specture System](https://github.com/specture-system/specture) - -This document outlines the structure and best practices for writing spec files in Specture. +> This project uses the [Specture System](https://github.com/specture-system/specture), and this document outlines how it works. As the Specture System is improved and updated, this file will also be updated. ## Overview -Specs are living documents that describe planned changes to the system. They serve as a blueprint for implementation and a historical record of design decisions. - -## Spec File Structure - -Each spec file should be a markdown document in the `specs/` directory with the following sections: - -### Title - -The spec should start with a clear, descriptive H1 heading that summarizes what is being proposed. - -```markdown -# Feature Name or Change Description -``` +Specs are design documents that describe planned changes to the system. They serve as a blueprint for implementation and a historical record of design decisions. They are continually improved during the design and implementation of a change, but left static after the change is complete. -### Brief Description +This system is inspired by the [PEP](https://peps.python.org/) (Python Enhancement Proposal) and [BIP](https://github.com/bitcoin/bips) (Bitcoin Improvement Proposal) systems, adapting their formal proposal processes for general software development. -A concise overview (2-4 paragraphs) that explains: -- What is being proposed -- Why it's needed -- What problem it solves -- High-level approach - -### Design Decisions +## Spec Scope -This section documents the design exploration process. For each major decision point: +**Specs are for planned changes**: new features, major refactors, redesigns, and tooling improvements. Use the issue tracker for bugs: cases where the software doesn't match what's described in the specs. -**Format:** -```markdown -## Design Decisions +In traditional project management, this scope would be split between epics (grouping work) and issues (individual tasks). Specture consolidates this: a spec includes the design rationale (why), the decisions (what and how), and the implementation task list all in one document. This keeps related information together and makes it easier for the reader to understand the full context. An individual spec can vary wildly in size, from as large as a traditional epic to as small as a tiny UI improvement. -### Decision Point Name +### When to split or combine specs -Brief context about what needs to be decided. +A spec should be a coherent unit of work. Split specs when changes are independent: they can be implemented and deployed separately, have different design rationales, or solve different problems. Keep specs together when they share design decisions or task dependencies. -#### Option 1: [Name] -**Pros:** -- Advantage 1 -- Advantage 2 +Examples: -**Cons:** -- Disadvantage 1 -- Disadvantage 2 +- One spec: "Add authentication system" (related design choices, shared infrastructure) +- Two specs: "Add authentication" and "Redesign dashboard UI" (independent changes) +- One minimal spec: "Rename demo app consistently" (small but still a planned change) -#### Option 2: [Name] -**Pros:** -- Advantage 1 -- Advantage 2 +## Spec File Structure -**Cons:** -- Disadvantage 1 -- Disadvantage 2 +Each spec file should be a Markdown document with a numeric prefix in the `specs/` directory, for example `specs/000-mvp.md`. -**Selected Approach:** [Chosen option and rationale] -``` +**Example format:** -Include as many decision points as needed. This creates a valuable historical record of why certain choices were made. +```markdown +--- +status: draft +author: Your Name +creation_date: 2025-12-18 +--- -### Task List +# Feature or Change Name -A detailed breakdown of implementation tasks using markdown checklists. Split into logical sections if needed. +Description as paragraphs and/or bulleted list. -**Format:** -```markdown ## Task List -### Phase 1: Foundation +### Foundation + - [ ] Task 1 - [ ] Task 2 - [ ] Task 3 -### Phase 2: Core Implementation +### Core Implementation + - [ ] Task 1 - [ ] Task 2 -### Phase 3: Polish & Documentation +### Polish and Documentation + - [ ] Task 1 - [ ] Task 2 ``` -**Task List Best Practices:** +### Frontmatter + +Each spec should begin with YAML frontmatter containing metadata: + +#### Required Fields + +- `status` + - `draft` - Spec is in the process of being written and improved upon + - `approved` - Spec has been approved and is awaiting implementation + - `in-progress` - Implementation is underway + - `completed` - All tasks have been completed + - `rejected` - Spec was reviewed but rejected + +#### Optional Fields + +- `author` - Person(s) who proposed or wrote the spec +- `creation_date` - Date the spec was created (YYYY-MM-DD format) +- `approved_by` - Person(s) who approved the spec +- `approval_date` - Date the spec was approved (YYYY-MM-DD format) + +### Title + +The spec should start with a clear, descriptive H1 heading that summarizes what is being proposed. + +### Description + +An overview of the proposed change. It might be a couple sentences for a small change or dozens of paragraphs for a large change. + +A few things to consider including: + +- What is being proposed +- Why it's needed +- What problem it solves +- High-level approach + +Feel free to use paragraph form or bulleted list form, whichever better matches the requirements of clearly describing the proposal. + +For large descriptions, please add separate sections with their own headers, for example: `## Ideas`, `## Goals`, `## Benefits`. + +### Design Decisions + +An optional section to document the design process. For each major decision made during the design process, include the options considered along with the pros and cons of each. This creates a valuable historical record of why certain choices were made. + +The number of decisions mentioned will most likely be proportional to the size of the change being discussed. Include as many decision points as needed. There is no obligation to include them for small specs or changes with trivial design choices. + +### Task List + +A detailed breakdown of implementation tasks using markdown checklists. Split into logical sections if needed. + +#### Task List Best Practices + - Make tasks specific and actionable - Order tasks logically (dependencies first) - Group related tasks into sections -- Include testing, documentation, and deployment tasks -- Keep individual tasks reasonably sized (completable in one session) +- Include testing, documentation, and deployment tasks where applicable +- Keep individual tasks reasonably sized and self-contained +- Avoid getting into nitty-gritty implementation details ## File Naming -Use descriptive, kebab-case filenames: -- `add-authentication-system.md` -- `refactor-database-layer.md` -- `redesign-api-endpoints.md` +Use descriptive, kebab-case filenames with a numeric prefix: + +- `000-mvp.md` +- `001-add-authentication-system.md` +- `013-refactor-database-layer.md` +- `314-redesign-api-endpoints.md` ## Workflow -1. **Create Spec**: Write the spec file with all required sections -2. **Submit PR**: Open a pull request adding the spec to `specs/` -3. **Discussion**: Team discusses and refines the spec in PR comments -4. **Approval**: Once approved, merge the spec PR -5. **Implementation**: Work through the task list, checking off items as completed -6. **Update**: Keep the spec updated as implementation reveals new details +### Draft -## Optional Sections +1. Create a new spec file with frontmatter status set to `draft` +2. Write the spec with required sections: Title, Description, and Task List. Include Design Decisions if there are meaningful choices to document +3. Keep the spec updated as you refine the proposal +4. Open pull/merge requests to share and refine the spec with the team +5. The spec may go through multiple iterations while still in draft status as it evolves -Specs may include additional sections as needed: -- **Dependencies**: External libraries, services, or other specs -- **Security Considerations**: Security implications and mitigations -- **Performance Impact**: Expected performance characteristics -- **Migration Strategy**: For changes affecting existing systems -- **Testing Strategy**: Approach to testing the change -- **Rollback Plan**: How to revert if needed -- **Open Questions**: Unresolved items requiring further discussion +#### Tips -## Example Spec Template +- **Be clear, not clever**: Write for future readers who may not have context +- **Document alternatives**: Even rejected options are valuable to record +- **Link to discussions**: Reference pull request[^1] comments, issues, or other specs +- **Focus on "why"**: The code shows "how", the spec should explain "why" -```markdown -# [Feature/Change Name] +### Approved -## Description +It is up to the project maintainers to determine when they are ready to merge a spec with the status set to `approved`. The requirements for what defines an approved spec will vary by project. -[2-4 paragraphs describing what, why, and how] +1. Once the team agrees the spec is ready for implementation, update status to `approved` in a pull request +2. Merge the pull request with the updated status +3. Implementation can now begin -## Design Decisions +### In-Progress -### [Decision Point 1] +1. Implementation begins once a spec is `approved` +2. Work through the task list, checking off items as completed +3. Keep the spec updated as implementation reveals new details +4. When all tasks are completed, move to `completed` status -Context for this decision. +### Completed -#### Option A: [Name] -**Pros:** -- Pro 1 -- Pro 2 +1. Mark the spec status as `completed` when all tasks in its task list are checked off +2. If there is still remaining work to be done for a change, be sure that the task list reflects this reality and keep the status as `in-progress` -**Cons:** -- Con 1 -- Con 2 +### Rejected -#### Option B: [Name] -**Pros:** -- Pro 1 -- Pro 2 +For most rejected specs, the project maintainers will not merge the spec. There's no reason to merge a proposal you don't intend to implement. -**Cons:** -- Con 1 -- Con 2 +However, some rejected specs may be useful to merge with the status set to `rejected`. These can act as a historical record of what was considered and rejected. The important thing in these cases is to clearly document **why** a proposal was rejected. -**Selected Approach:** Option A - [rationale] +## Precedence System -## Task List +The requirements listed in one spec may become outdated with time. Once a spec has status `completed`, it should be treated as a historical record and not retroactively updated. It is a bad idea to try to go back and update completed specs. This would be tedious and error-prone. Inevitably, something would be missed. -### Phase 1: Setup -- [ ] Task 1 -- [ ] Task 2 +The exception is to fix overlooked mistakes: typos, errors in documentation, or factual inaccuracies should be corrected. -### Phase 2: Implementation -- [ ] Task 3 -- [ ] Task 4 +Instead, we rely on a simple precedence system. The numeric prefix at the beginning of each spec defines its precedence. The higher the number is, the higher the precedence. If two specs contradict each other on any particular point, the higher numbered spec takes precedence. -### Phase 3: Finalization -- [ ] Task 5 -- [ ] Task 6 -``` +In general, the numbers should be incremented over time with each new spec added to the project. -## Tips +Some tricky situations might arise where it becomes necessary to number specs non-incrementally, especially when a team is working on drafting multiple specs at once. A project's spec number assignment system should be optimized for the needs of that project. Overall, no matter what scheme you determine for assigning numbers to each new spec, stick to the rule that higher number means higher precedence. + +[^1]: The usage of "pull request" in this document also applies to GitLab merge requests. -- **Be clear, not clever**: Write for future readers who may not have context -- **Document alternatives**: Even rejected options are valuable to record -- **Update as you go**: Specs should evolve during implementation -- **Link to discussions**: Reference PR comments, issues, or other specs -- **Focus on "why"**: The code shows "how", the spec should explain "why"