docs: 2025-12-18 improvements

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

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
 

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.