mirror of
https://github.com/meshtastic/Meshtastic-Android.git
synced 2026-05-12 00:28:20 -04:00
docs: Update specs and governance for Android M3 accessibility (#5392)
This commit is contained in:
James Rich
113
.github/agents/speckit.brownfield.bootstrap.agent.md
vendored
Normal file
113
.github/agents/speckit.brownfield.bootstrap.agent.md
vendored
Normal file
@@ -0,0 +1,113 @@
|
||||
---
|
||||
description: Generate spec-kit configuration tailored to the existing codebase
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: brownfield -->
|
||||
<!-- Config: .specify/extensions/brownfield/ -->
|
||||
# Bootstrap Spec-Kit
|
||||
|
||||
Generate a customized spec-kit configuration for an existing codebase. Uses the project profile from `/speckit.brownfield.scan` (or performs a scan if none exists) to create a constitution, templates, and agent configuration that match the project's actual architecture, tech stack, and conventions.
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty). The user may specify preferences (e.g., "strict TDD", "minimal constitution"), a target directory for a monorepo module, or request specific template customizations.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Verify the current directory is a git repository
|
||||
2. Verify a spec-kit project exists by checking for `.specify/` directory (run `specify init` first if missing)
|
||||
3. Check if a project profile exists from a previous scan — if not, run a scan first
|
||||
|
||||
## Outline
|
||||
|
||||
1. **Load or generate project profile**: Check if `/speckit.brownfield.scan` has been run:
|
||||
- If a project profile exists, use it
|
||||
- If not, perform an inline scan to gather tech stack, architecture, and conventions
|
||||
- Confirm the profile with the user before proceeding
|
||||
|
||||
2. **Generate constitution**: Create `.specify/memory/constitution.md` tailored to the project:
|
||||
|
||||
The constitution **MUST** include:
|
||||
- **Project identity**: Name, purpose, primary language(s), architecture pattern
|
||||
- **Code boundaries**: Which directories contain which types of code (e.g., "frontend code lives in `client/`, backend in `server/`")
|
||||
- **Naming conventions**: File naming, variable naming, branch naming as detected
|
||||
- **Testing requirements**: Test framework, test location, coverage expectations
|
||||
- **Dependency rules**: How modules depend on each other, what imports are allowed
|
||||
- **Quality gates**: Linting, formatting, CI checks that must pass
|
||||
|
||||
The constitution **MUST NOT**:
|
||||
- Override existing project standards without user confirmation
|
||||
- Invent conventions that don't exist in the codebase
|
||||
- Include generic boilerplate unrelated to the actual project
|
||||
|
||||
3. **Customize spec template**: Modify `.specify/templates/spec-template.md` to reflect the project:
|
||||
- Add project-specific sections (e.g., "Database Migrations" for projects with ORMs)
|
||||
- Include architecture-aware requirements (e.g., "Frontend Requirements" and "API Requirements" for full-stack projects)
|
||||
- Reference actual module paths instead of generic placeholders
|
||||
|
||||
4. **Customize plan template**: Modify `.specify/templates/plan-template.md` to reflect the project:
|
||||
- Include module-aware implementation sections (e.g., separate phases for frontend/backend)
|
||||
- Reference actual test frameworks and build tools
|
||||
- Include project-specific complexity factors
|
||||
|
||||
5. **Customize tasks template**: Modify `.specify/templates/tasks-template.md` to reflect the project:
|
||||
- Task phases should map to the project's actual module structure
|
||||
- Include project-specific setup tasks (e.g., database migration, dependency install)
|
||||
- Reference actual test commands (e.g., `npm test`, `pytest`, `go test ./...`)
|
||||
|
||||
6. **Generate AGENTS.md** (if multi-module): For monorepos and multi-module projects:
|
||||
- Define agent boundaries per module
|
||||
- Specify which agent owns which directories
|
||||
- Set up inter-agent communication rules
|
||||
|
||||
7. **Present changes**: Show the user what will be created or modified:
|
||||
|
||||
```markdown
|
||||
# Bootstrap Plan
|
||||
|
||||
| File | Action | Description |
|
||||
|------|--------|-------------|
|
||||
| `.specify/memory/constitution.md` | Create | Project-specific constitution with detected conventions |
|
||||
| `.specify/templates/spec-template.md` | Modify | Add project-specific sections (Database Migrations, API Contract) |
|
||||
| `.specify/templates/plan-template.md` | Modify | Add module-aware phases (frontend, backend, shared) |
|
||||
| `.specify/templates/tasks-template.md` | Modify | Add actual test commands and build steps |
|
||||
| `AGENTS.md` | Create | Agent boundaries for frontend and backend modules |
|
||||
|
||||
Proceed with bootstrap? (confirm before writing)
|
||||
```
|
||||
|
||||
8. **Execute bootstrap**: After user confirmation, write all files.
|
||||
|
||||
9. **Report**:
|
||||
|
||||
```markdown
|
||||
# Bootstrap Complete
|
||||
|
||||
| Artifact | Status |
|
||||
|----------|--------|
|
||||
| Constitution | ✅ Created — 12 rules from detected conventions |
|
||||
| Spec template | ✅ Customized — added Database Migrations, API Contract sections |
|
||||
| Plan template | ✅ Customized — frontend/backend phase split |
|
||||
| Tasks template | ✅ Customized — actual test commands included |
|
||||
| AGENTS.md | ✅ Created — 2 agents (frontend, backend) |
|
||||
|
||||
## Next Steps
|
||||
- Review `.specify/memory/constitution.md` and adjust any rules
|
||||
- Run `/speckit.brownfield.validate` to verify configuration matches project
|
||||
- Run `/speckit.brownfield.migrate` to reverse-engineer specs for existing features
|
||||
- Start new features with `/speckit.specify` — templates are now project-aware
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Always confirm before writing** — show the bootstrap plan and wait for approval
|
||||
- **Never overwrite without asking** — if constitution or templates already exist, show a diff and ask
|
||||
- **Derive from reality** — every constitution rule must trace to something detected in the codebase
|
||||
- **No invented conventions** — if the project has no consistent pattern for something, say so instead of guessing
|
||||
- **Respect existing spec-kit setup** — if `.specify/` already has customizations, merge rather than replace
|
||||
- **Module-aware** — for monorepos, generate configuration that respects module boundaries
|
||||
128
.github/agents/speckit.brownfield.migrate.agent.md
vendored
Normal file
128
.github/agents/speckit.brownfield.migrate.agent.md
vendored
Normal file
@@ -0,0 +1,128 @@
|
||||
---
|
||||
description: Incrementally adopt SDD for existing features with reverse-engineered
|
||||
specs
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: brownfield -->
|
||||
<!-- Config: .specify/extensions/brownfield/ -->
|
||||
# Migrate Existing Features
|
||||
|
||||
Reverse-engineer spec-kit artifacts (spec.md, plan.md, tasks.md) for features that were built before spec-kit was adopted. This brings existing work into the SDD workflow so teams can track, refine, and extend features using spec-kit commands.
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty). The user may specify a feature or module to migrate (e.g., "auth system", "payments module"), a branch name, or "all" to migrate everything.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Verify a spec-kit project exists by checking for `.specify/` directory
|
||||
2. Verify git is available and the project is a git repository
|
||||
3. Verify the project has existing source code to migrate (not an empty project)
|
||||
4. Verify constitution exists (recommend running `/speckit.brownfield.bootstrap` first if missing)
|
||||
|
||||
## Outline
|
||||
|
||||
1. **Identify migration targets**: Determine what to migrate based on user input:
|
||||
|
||||
| Input | Action |
|
||||
|-------|--------|
|
||||
| Specific feature name | Locate the feature in the codebase by searching for related files, modules, or directories |
|
||||
| Specific branch name | Analyze the branch's commits and changed files to identify the feature scope |
|
||||
| Module path | Treat the entire module as a single feature to migrate |
|
||||
| `all` | List all identifiable features and let the user select which to migrate |
|
||||
| No input | Show a list of detected features and ask the user to pick one |
|
||||
|
||||
2. **Detect feature boundaries**: For each migration target, determine its scope:
|
||||
- **Files**: Which source files implement this feature
|
||||
- **Tests**: Which test files cover this feature
|
||||
- **Dependencies**: What other modules or services this feature depends on
|
||||
- **API surface**: Endpoints, functions, or interfaces exposed by this feature
|
||||
- **Database**: Migrations, models, or schema changes related to this feature
|
||||
|
||||
3. **Reverse-engineer spec.md**: Analyze the code to reconstruct what the feature does:
|
||||
- **User scenarios**: Infer from test cases, route handlers, and UI components
|
||||
- **Requirements**: Extract from code behavior, validation rules, and error handling
|
||||
- **Success criteria**: Derive from test assertions and acceptance patterns
|
||||
- **Assumptions**: Note any hardcoded values, environment dependencies, or implicit requirements
|
||||
- Mark the spec as `status: migrated` to distinguish from specs created through the normal workflow
|
||||
|
||||
4. **Reverse-engineer plan.md**: Reconstruct the implementation approach:
|
||||
- **Technical context**: Actual frameworks, libraries, and patterns used
|
||||
- **Project structure**: Where the feature's code lives in the project
|
||||
- **Complexity assessment**: Based on file count, line count, and dependency depth
|
||||
|
||||
5. **Reverse-engineer tasks.md**: Create a task list reflecting what was actually built:
|
||||
- Each major component or module becomes a task group
|
||||
- Mark all tasks as `[x]` (completed) since the feature already exists
|
||||
- Include test tasks based on actual test files found
|
||||
- Note any gaps: code without tests, features without error handling
|
||||
|
||||
6. **Create feature branch and artifacts**: For each migrated feature:
|
||||
- Create a feature directory: `specs/{feature-name}/`
|
||||
- Write `spec.md`, `plan.md`, and `tasks.md` into the feature directory
|
||||
- Do **not** create a git branch — the feature already exists on its branch or main
|
||||
|
||||
7. **Present migration plan**: Show what will be created before writing:
|
||||
|
||||
```markdown
|
||||
# Migration Plan: User Authentication
|
||||
|
||||
## Detected Scope
|
||||
| Category | Files | Lines |
|
||||
|----------|-------|-------|
|
||||
| Source | 8 files | ~420 lines |
|
||||
| Tests | 3 files | ~180 lines |
|
||||
| Migrations | 2 files | ~45 lines |
|
||||
|
||||
## Artifacts to Generate
|
||||
| File | Content |
|
||||
|------|---------|
|
||||
| `specs/user-auth/spec.md` | 4 user scenarios, 12 requirements, 6 success criteria |
|
||||
| `specs/user-auth/plan.md` | 3 implementation phases, 8 technical decisions |
|
||||
| `specs/user-auth/tasks.md` | 14 tasks (all completed), 2 gaps identified |
|
||||
|
||||
## Gaps Found
|
||||
- ⚠️ No error handling tests for expired tokens
|
||||
- ⚠️ No rate limiting on login endpoint
|
||||
|
||||
Proceed with migration?
|
||||
```
|
||||
|
||||
8. **Execute migration**: After user confirmation, write all artifacts.
|
||||
|
||||
9. **Report**:
|
||||
|
||||
```markdown
|
||||
# Migration Complete: User Authentication
|
||||
|
||||
| Artifact | Status |
|
||||
|----------|--------|
|
||||
| spec.md | ✅ Created — 4 scenarios, 12 requirements |
|
||||
| plan.md | ✅ Created — 3 phases |
|
||||
| tasks.md | ✅ Created — 14/14 tasks complete |
|
||||
|
||||
## Identified Gaps
|
||||
1. No error handling tests for expired tokens → consider `/speckit.specify` for a follow-up feature
|
||||
2. No rate limiting on login endpoint → consider `/speckit.bugfix.report` to track
|
||||
|
||||
## Next Steps
|
||||
- Review generated artifacts in `specs/user-auth/`
|
||||
- Use `/speckit.refine.update` to adjust any inaccurate specs
|
||||
- Use `/speckit.specify` for new features — they'll follow the same SDD workflow
|
||||
- Run `/speckit.brownfield.migrate` again for additional features
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Always confirm before writing** — show the migration plan and wait for user approval
|
||||
- **Honest assessment** — if the code is unclear or poorly documented, say so in the spec rather than inventing explanations
|
||||
- **Mark as migrated** — all migrated specs must include `status: migrated` to distinguish from fresh specs
|
||||
- **Identify gaps** — actively look for missing tests, error handling, or documentation and report them
|
||||
- **Non-destructive** — never modify existing source code, only create spec artifacts
|
||||
- **One feature at a time** — for "all" input, migrate features sequentially with confirmation between each
|
||||
- **Respect constitution** — generated artifacts must follow the project's constitution rules
|
||||
121
.github/agents/speckit.brownfield.scan.agent.md
vendored
Normal file
121
.github/agents/speckit.brownfield.scan.agent.md
vendored
Normal file
@@ -0,0 +1,121 @@
|
||||
---
|
||||
description: Auto-discover project structure, tech stack, frameworks, and architecture
|
||||
patterns
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: brownfield -->
|
||||
<!-- Config: .specify/extensions/brownfield/ -->
|
||||
# Scan Project
|
||||
|
||||
Analyze an existing codebase to discover its technology stack, architecture patterns, module structure, and coding conventions. This produces a project profile that the bootstrap command uses to generate tailored spec-kit configuration.
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty). The user may specify a subdirectory to scan (e.g., "backend/"), a focus area (e.g., "only frontend"), or request a specific depth of analysis.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Verify the current directory is a git repository
|
||||
2. Verify this is an existing project with source code (not an empty repo)
|
||||
|
||||
## Outline
|
||||
|
||||
1. **Detect tech stack**: Identify languages, frameworks, and tools by scanning:
|
||||
|
||||
| Signal | What to Check |
|
||||
|--------|--------------|
|
||||
| **Languages** | File extensions (`.py`, `.ts`, `.go`, `.java`, `.rs`, etc.) and their relative proportions |
|
||||
| **Package managers** | `package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `build.gradle` |
|
||||
| **Frameworks** | Dependencies in package files (React, Django, Spring, Express, Rails, etc.) |
|
||||
| **Build tools** | `Makefile`, `webpack.config.js`, `vite.config.ts`, `Dockerfile`, `docker-compose.yml` |
|
||||
| **CI/CD** | `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `Jenkinsfile` |
|
||||
| **Testing** | Test directories, test frameworks in dependencies (`jest`, `pytest`, `go test`, `JUnit`) |
|
||||
|
||||
2. **Analyze architecture**: Identify the project's structural patterns:
|
||||
|
||||
| Pattern | Indicators |
|
||||
|---------|-----------|
|
||||
| **Monolith** | Single source tree, one entry point, shared database config |
|
||||
| **Monorepo** | Multiple `package.json`/`go.mod` files, workspace config, `packages/` or `apps/` directories |
|
||||
| **Microservices** | Multiple Dockerfiles, service directories, API gateway config |
|
||||
| **Frontend + Backend** | Separate `client/`/`server/` or `frontend/`/`backend/` directories |
|
||||
| **Library/Package** | `setup.py`, `lib/` directory, published package config |
|
||||
| **MVC** | `models/`, `views/`, `controllers/` directories |
|
||||
| **Layered** | `domain/`, `application/`, `infrastructure/`, `presentation/` directories |
|
||||
|
||||
3. **Map module structure**: For monorepos and multi-module projects:
|
||||
- Identify each module/package/service and its purpose
|
||||
- Detect inter-module dependencies (imports, shared types)
|
||||
- Note module boundaries (what code belongs where)
|
||||
- Identify shared libraries or utilities
|
||||
|
||||
4. **Extract conventions**: Detect existing coding patterns:
|
||||
- **Naming**: File naming (camelCase, kebab-case, snake_case), directory naming
|
||||
- **Branching**: Existing branch names and patterns from `git branch -a`
|
||||
- **Commit style**: Recent commit message patterns from `git log --oneline -20`
|
||||
- **Testing**: Test file location (`__tests__/`, `*_test.go`, `test_*.py`), test naming
|
||||
- **Documentation**: README structure, inline docs, API docs
|
||||
|
||||
5. **Detect existing governance**: Check for files that indicate existing project standards:
|
||||
- `CONTRIBUTING.md`, `ARCHITECTURE.md`, `ADR/` (Architecture Decision Records)
|
||||
- `.editorconfig`, linter configs (`.eslintrc`, `.flake8`, `rustfmt.toml`)
|
||||
- `CLAUDE.md`, `AGENTS.md`, `.specify/` (existing spec-kit setup)
|
||||
|
||||
6. **Output project profile**:
|
||||
|
||||
```markdown
|
||||
# Project Profile
|
||||
|
||||
## Tech Stack
|
||||
| Category | Detected |
|
||||
|----------|----------|
|
||||
| **Primary language** | TypeScript (68%), Python (32%) |
|
||||
| **Frontend** | React 18, Vite, TailwindCSS |
|
||||
| **Backend** | FastAPI, SQLAlchemy, PostgreSQL |
|
||||
| **Testing** | Jest (frontend), pytest (backend) |
|
||||
| **CI/CD** | GitHub Actions |
|
||||
| **Package manager** | npm (frontend), pip (backend) |
|
||||
|
||||
## Architecture
|
||||
- **Pattern**: Frontend + Backend (separated)
|
||||
- **Frontend**: `client/` — React SPA
|
||||
- **Backend**: `server/` — FastAPI REST API
|
||||
- **Database**: PostgreSQL (via SQLAlchemy ORM)
|
||||
|
||||
## Module Map
|
||||
| Module | Path | Purpose | Dependencies |
|
||||
|--------|------|---------|-------------|
|
||||
| Frontend | `client/` | React SPA | Backend API |
|
||||
| Backend | `server/` | REST API | Database |
|
||||
| Shared | `shared/` | Type definitions | — |
|
||||
|
||||
## Conventions
|
||||
- **File naming**: kebab-case (frontend), snake_case (backend)
|
||||
- **Branch pattern**: `feat/*`, `fix/*`, `chore/*`
|
||||
- **Commit style**: Conventional Commits
|
||||
- **Test location**: `__tests__/` (frontend), `tests/` (backend)
|
||||
|
||||
## Existing Governance
|
||||
- ✅ CONTRIBUTING.md
|
||||
- ✅ .eslintrc.json
|
||||
- ❌ ARCHITECTURE.md
|
||||
- ❌ .specify/ (no spec-kit setup)
|
||||
|
||||
## Recommendations
|
||||
- Run `/speckit.brownfield.bootstrap` to generate tailored spec-kit configuration
|
||||
- Constitution should enforce: kebab-case files (frontend), snake_case (backend)
|
||||
- Feature specs should map to the frontend/backend split
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Read-only** — this command never modifies any files
|
||||
- **Respect .gitignore** — never scan `node_modules/`, `vendor/`, `dist/`, `.venv/`, or other ignored directories
|
||||
- **Proportional analysis** — report language percentages based on actual file counts or line counts
|
||||
- **No assumptions** — only report what is actually detected in the codebase
|
||||
- **Handle empty results** — if a category has nothing detected, say "Not detected" rather than guessing
|
||||
94
.github/agents/speckit.brownfield.validate.agent.md
vendored
Normal file
94
.github/agents/speckit.brownfield.validate.agent.md
vendored
Normal file
@@ -0,0 +1,94 @@
|
||||
---
|
||||
description: Verify bootstrap output matches actual project structure and conventions
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: brownfield -->
|
||||
<!-- Config: .specify/extensions/brownfield/ -->
|
||||
# Validate Bootstrap
|
||||
|
||||
Verify that the spec-kit configuration generated by `/speckit.brownfield.bootstrap` accurately reflects the actual project structure, conventions, and architecture. Reports mismatches and suggests corrections.
|
||||
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty). The user may specify a focus area (e.g., "only constitution", "only templates") or request verbose output.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. Verify a spec-kit project exists by checking for `.specify/` directory
|
||||
2. Verify git is available and the project is a git repository
|
||||
3. Verify at least one bootstrap artifact exists (constitution, customized templates, or AGENTS.md)
|
||||
|
||||
## Outline
|
||||
|
||||
1. **Validate constitution**: Check `.specify/memory/constitution.md` against the actual codebase:
|
||||
|
||||
| Check | How |
|
||||
|-------|-----|
|
||||
| **Language references** | Verify mentioned languages actually exist in the codebase |
|
||||
| **Directory references** | Verify all referenced paths (`client/`, `server/`, etc.) exist |
|
||||
| **Framework references** | Verify mentioned frameworks are in dependency files |
|
||||
| **Naming conventions** | Sample 20 files and check if naming rules match reality |
|
||||
| **Test location** | Verify test directories mentioned in constitution exist |
|
||||
| **Branch pattern** | Check if branch naming rules match actual branches in `git branch -a` |
|
||||
|
||||
2. **Validate templates**: Check customized spec/plan/tasks templates:
|
||||
|
||||
| Check | How |
|
||||
|-------|-----|
|
||||
| **Module references** | Verify template sections reference actual modules/directories |
|
||||
| **Test commands** | Verify test commands in tasks template actually work |
|
||||
| **Build commands** | Verify build commands reference real scripts from package files |
|
||||
| **Section relevance** | Flag template sections that reference non-existent project aspects |
|
||||
|
||||
3. **Validate AGENTS.md** (if exists): Check agent configuration:
|
||||
|
||||
| Check | How |
|
||||
|-------|-----|
|
||||
| **Directory ownership** | Verify each agent's directories exist |
|
||||
| **No overlaps** | Check that no directory is owned by multiple agents |
|
||||
| **No orphans** | Check that all source directories are covered by at least one agent |
|
||||
|
||||
4. **Detect drift**: Check if the project has changed since bootstrap:
|
||||
- New directories or modules added since constitution was generated
|
||||
- Dependencies added or removed since bootstrap
|
||||
- New branch patterns that don't match constitution rules
|
||||
|
||||
5. **Output validation report**:
|
||||
|
||||
```markdown
|
||||
# Validation Report
|
||||
|
||||
## Constitution
|
||||
| Rule | Status | Detail |
|
||||
|------|--------|--------|
|
||||
| Primary language: TypeScript | ✅ Pass | 68% of source files |
|
||||
| Frontend in `client/` | ✅ Pass | Directory exists, contains React code |
|
||||
| Backend in `server/` | ✅ Pass | Directory exists, contains FastAPI code |
|
||||
| Test location: `__tests__/` | ⚠️ Drift | Also found tests in `tests/` (not mentioned) |
|
||||
| Branch pattern: `feat/*` | ✅ Pass | 8/10 recent branches match |
|
||||
|
||||
## Templates
|
||||
| Template | Status | Detail |
|
||||
|----------|--------|--------|
|
||||
| Spec template | ✅ Pass | All custom sections map to real project aspects |
|
||||
| Plan template | ⚠️ Drift | References `shared/` module — directory renamed to `common/` |
|
||||
| Tasks template | ✅ Pass | Test commands verified |
|
||||
|
||||
## Summary
|
||||
- **Checks passed**: 9/11
|
||||
- **Drift detected**: 2 items
|
||||
- **Action needed**: Update plan template (`shared/` → `common/`), add `tests/` to constitution
|
||||
```
|
||||
|
||||
## Rules
|
||||
|
||||
- **Read-only** — this command never modifies any files
|
||||
- **Evidence-based** — every pass/fail must cite specific files or directories as evidence
|
||||
- **Actionable output** — for every failure or drift, suggest the specific fix
|
||||
- **Non-blocking** — drift warnings don't mean the configuration is broken, just that it could be improved
|
||||
- **Respect .gitignore** — never scan ignored directories when validating
|
||||
290
.github/agents/speckit.optimize.learn.agent.md
vendored
Normal file
290
.github/agents/speckit.optimize.learn.agent.md
vendored
Normal file
@@ -0,0 +1,290 @@
|
||||
---
|
||||
description: Analyze AI session patterns to suggest constitution rules or memory entries.
|
||||
handoffs:
|
||||
- label: Amend constitution
|
||||
agent: speckit.constitution
|
||||
prompt: Add the approved rules to the constitution
|
||||
- label: Optimize governance
|
||||
agent: speckit.optimize.run
|
||||
prompt: Run a full governance audit after adding new rules
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: optimize -->
|
||||
<!-- Config: .specify/extensions/optimize/ -->
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
Arguments: `--rules-only` to skip memory suggestions, `--memory-only` to skip rule suggestions, `--since <commit>` to limit analysis scope.
|
||||
|
||||
## Goal
|
||||
|
||||
Analyze the current AI session's work to identify patterns of mistakes, repetitive corrections, and governance gaps. Produce suggestions for new constitution rules or memory entries that would prevent these patterns in future sessions. Apply **nothing** without explicit user consent.
|
||||
|
||||
This command answers: "What did this AI session learn the hard way that future sessions should know from the start?"
|
||||
|
||||
**When to use**: End of an implementation session, before creating a PR/MR. Run while the session context is still fresh.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
- **Suggest-only**: NEVER add rules to the constitution or write memory files without explicit user consent. Always present proposals first.
|
||||
- **Evidence-based**: Every suggestion MUST cite specific files, diffs, or session events as evidence. No speculative rules.
|
||||
- **Spec-kit standard paths**: Use `.specify/memory/constitution.md` (follow redirects) for the constitution. Memory files go to the tool's memory system (e.g., `.claude/` for Claude Code).
|
||||
- **Minimal governance growth**: Prefer memory entries over constitution rules unless the pattern affects all team members and all AI tools. Constitution rules have a token cost paid on every future session.
|
||||
- **Deterministic proposals**: Every proposed rule MUST be concrete, MUST/SHOULD qualified, and deterministic — no vague language.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Determine Analysis Scope
|
||||
|
||||
Identify the work done in the current session:
|
||||
|
||||
1. **Git-based scope** (primary):
|
||||
- Run `git log --oneline` to find recent commits
|
||||
- If `--since <commit>` is provided, use that as the starting point
|
||||
- Otherwise, heuristically identify the session boundary: look for commits from today, or the most recent cluster of commits by the current author
|
||||
- Record the commit range as `SESSION_RANGE`
|
||||
|
||||
2. **Diff analysis**:
|
||||
- Run `git diff <SESSION_RANGE>` to get the full session diff
|
||||
- Run `git diff --stat <SESSION_RANGE>` for a file-level overview
|
||||
- Record all modified files as `SESSION_FILES`
|
||||
|
||||
3. **Session metadata**:
|
||||
- Count: commits, files modified, lines added, lines removed
|
||||
- Identify: primary language(s), directories touched, components affected
|
||||
|
||||
If no git changes are found, inform the user: "No session changes detected. This command analyzes git history to find patterns. Run it after making changes."
|
||||
|
||||
### 2. Load Current Governance
|
||||
|
||||
Load the constitution (following the standard resolution chain from `.specify/memory/constitution.md`). Parse into a flat list of rules for gap analysis.
|
||||
|
||||
Load config from `.specify/extensions/optimize/optimize-config.yml` (or defaults) for:
|
||||
- `min_corrections_to_flag` (default: 2)
|
||||
- `include_memory_suggestions` (default: true)
|
||||
- `include_rule_suggestions` (default: true)
|
||||
|
||||
### 3. Detect Mistake Patterns
|
||||
|
||||
Analyze the session's git history for evidence of repeated corrections:
|
||||
|
||||
#### 3a. Repeated Correction Patterns
|
||||
|
||||
For each file in `SESSION_FILES`, check commit history within `SESSION_RANGE`:
|
||||
|
||||
- **Same-file re-edits**: Files modified in 3+ separate commits within the session. This suggests the AI got it wrong initially and had to correct multiple times. Record the file and the nature of each change.
|
||||
|
||||
- **Revert patterns**: Look for pairs of commits where the second commit undoes part of the first (same lines modified in opposite directions). This indicates the AI made a wrong choice that was immediately corrected.
|
||||
|
||||
- **Fix-after-fix chains**: Commits with messages containing correction indicators: "fix", "actually", "oops", "correct", "should be", "typo", "missed", "forgot". Each represents a mistake the AI made.
|
||||
|
||||
- **Checkstyle/linter fix commits**: Commits that only fix style violations (detected by diffing against checkstyle or linter output). These indicate the AI didn't follow style rules the first time.
|
||||
|
||||
#### 3b. Repeated Transformation Patterns
|
||||
|
||||
Look for the same type of change applied to multiple files:
|
||||
|
||||
- **Boilerplate additions**: Same code pattern added to 3+ files (e.g., adding `this.` prefix, adding file headers, adding import ordering). If the AI had to manually apply the same transformation many times, it suggests a rule that should be automated.
|
||||
|
||||
- **Naming corrections**: Same type of rename applied multiple times (e.g., removing `Entity` suffix from non-entity classes, or adding it to entity classes). Suggests unclear naming rules.
|
||||
|
||||
- **Pattern enforcement**: Same structural change across files (e.g., converting `@Service` annotations to `@Bean` registration). Suggests the AI kept defaulting to a wrong pattern.
|
||||
|
||||
#### 3c. Constitution Violation Patterns
|
||||
|
||||
For each detected mistake pattern:
|
||||
|
||||
1. Search the constitution for a rule that should have prevented it
|
||||
2. If a rule exists:
|
||||
- The AI violated an existing rule → the rule may be ambiguous, poorly worded, or easy to miss
|
||||
- Record as: "Existing rule violated — suggest rewrite for clarity"
|
||||
3. If no rule exists:
|
||||
- The pattern represents a governance gap
|
||||
- Record as: "No existing rule — suggest new rule"
|
||||
|
||||
### 4. Detect Repetitive Task Patterns
|
||||
|
||||
Beyond mistakes, identify tasks the AI performed repeatedly that suggest missing automation or rules:
|
||||
|
||||
- **Manual enforcement**: Tasks that could be automated (e.g., repeatedly checking import order → should be enforced by a linter, repeatedly adding JavaDoc → should be caught by checkstyle)
|
||||
|
||||
- **Boilerplate generation**: Repeated creation of similar files (e.g., creating test classes with the same structure, creating DTOs with the same patterns). Suggests templates or generators would help.
|
||||
|
||||
- **Cross-file consistency**: Changes that required updating multiple files to stay consistent (e.g., adding a field to an entity requires updating the DTO, the mapper, and the test). Suggests a documentation or tooling gap.
|
||||
|
||||
### 5. Generate Proposals
|
||||
|
||||
For each detected pattern, generate a proposal. Proposals are either **constitution rules** or **memory entries**.
|
||||
|
||||
#### Constitution Rule Proposals
|
||||
|
||||
Only propose constitution rules when the pattern:
|
||||
- Affects all developers (not just one person's preference)
|
||||
- Applies across all AI tools (not tool-specific)
|
||||
- Is project-wide (not component-specific)
|
||||
- Would prevent the mistake in future sessions
|
||||
|
||||
Format for each proposed rule:
|
||||
|
||||
```markdown
|
||||
### Proposed Rule: <short title>
|
||||
|
||||
**Type**: Constitution Rule
|
||||
**Principle Placement**: <existing principle name, or "New Principle: <name>">
|
||||
**Severity**: MUST / SHOULD
|
||||
|
||||
**Rule Text**:
|
||||
> <Concrete, deterministic rule text. MUST/SHOULD qualified. No vague language.>
|
||||
|
||||
**Rationale**: <What session pattern triggered this>
|
||||
|
||||
**Evidence**:
|
||||
- `<file>:<line>` — <what happened>
|
||||
- Commit `<hash>` — <what the fix was>
|
||||
- Pattern repeated <N> times across <files>
|
||||
|
||||
**Enforcement Suggestion**: <How to automate: checkstyle rule, Gradle task, CI check, or "manual review only">
|
||||
|
||||
**Token Cost**: ~<estimated tokens this rule adds to the constitution>
|
||||
```
|
||||
|
||||
#### Memory Entry Proposals
|
||||
|
||||
Propose memory entries when the pattern:
|
||||
- Is specific to this user or project (not universal)
|
||||
- Is preference-based rather than governance-based
|
||||
- Would help the AI agent in future sessions without being a formal rule
|
||||
|
||||
Format for each proposed memory:
|
||||
|
||||
```markdown
|
||||
### Proposed Memory: <short title>
|
||||
|
||||
**Type**: Memory Entry
|
||||
**Memory Type**: feedback / user / project / reference
|
||||
**File Name**: <proposed filename, e.g., feedback_import_order.md>
|
||||
|
||||
**Content**:
|
||||
> <Proposed memory content, structured per the memory type's conventions>
|
||||
|
||||
**Rationale**: <What session pattern triggered this>
|
||||
|
||||
**Evidence**:
|
||||
- <specific examples from the session>
|
||||
```
|
||||
|
||||
### 6. Present Learning Report
|
||||
|
||||
Present all proposals to the user:
|
||||
|
||||
```markdown
|
||||
## Session Learning Report
|
||||
|
||||
**Session**: <commit range>
|
||||
**Files Modified**: <count>
|
||||
**Commits Analyzed**: <count>
|
||||
|
||||
### Session Patterns Detected
|
||||
|
||||
| # | Pattern | Occurrences | Type | Proposal |
|
||||
|---|---------|-------------|------|----------|
|
||||
| 1 | <pattern description> | X times | Mistake | Rule / Memory |
|
||||
| 2 | <pattern description> | X times | Repetitive | Rule / Memory |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
### Existing Rules Violated
|
||||
|
||||
| # | Rule | Principle | Violation Count | Issue |
|
||||
|---|------|-----------|-----------------|-------|
|
||||
| 1 | <rule text> | <principle> | X | Ambiguous / Easy to miss |
|
||||
|
||||
**Suggestion**: Rewrite for clarity → <proposed rewrite>
|
||||
|
||||
### Proposed Constitution Rules (<count>)
|
||||
|
||||
[List each proposed rule per format above]
|
||||
|
||||
### Proposed Memory Entries (<count>)
|
||||
|
||||
[List each proposed memory per format above]
|
||||
|
||||
### Summary
|
||||
|
||||
- **Total patterns detected**: X
|
||||
- **Constitution rules proposed**: X (adds ~Y tokens to governance)
|
||||
- **Memory entries proposed**: X
|
||||
- **Existing rules to rewrite**: X
|
||||
|
||||
**Which proposals would you like to apply?**
|
||||
Select by number, "all rules", "all memories", or "none".
|
||||
```
|
||||
|
||||
Wait for user selection. Do NOT apply anything without explicit consent.
|
||||
|
||||
### 7. Apply Approved Proposals
|
||||
|
||||
For each user-approved proposal:
|
||||
|
||||
**Constitution rules**:
|
||||
- Do NOT directly edit the constitution
|
||||
- Hand off to `/speckit.constitution` with the specific rule text, principle placement, and rationale
|
||||
- This ensures proper version bumping and governance compliance
|
||||
|
||||
**Memory entries**:
|
||||
- Write the memory file to the appropriate memory directory
|
||||
- Update the memory index (e.g., `MEMORY.md`)
|
||||
- Confirm each write to the user
|
||||
|
||||
**Rule rewrites** (for existing rules that were violated due to ambiguity):
|
||||
- Hand off to `/speckit.optimize.run --category ai_interpretability` for a targeted rewrite
|
||||
- Or hand off to `/speckit.constitution` for manual amendment
|
||||
|
||||
### 8. Output Summary
|
||||
|
||||
```markdown
|
||||
## Session Learning Complete
|
||||
|
||||
### Applied
|
||||
- Constitution rules handed to `/speckit.constitution`: X
|
||||
- Memory entries written: X
|
||||
- Rule rewrites suggested: X
|
||||
|
||||
### Declined
|
||||
- [List of declined proposals — preserved in report for future reference]
|
||||
|
||||
### Learning Report Saved
|
||||
- Report: `.specify/optimize/learning-report-<date>.md`
|
||||
|
||||
### Recommended Follow-Up
|
||||
- Run `/speckit.constitution` to formally add approved rules
|
||||
- Run `/speckit.optimize.run` to verify the new rules don't create contradictions
|
||||
- Run `/speckit.optimize.tokens` to check token budget after additions
|
||||
```
|
||||
|
||||
### 9. Save Learning Report
|
||||
|
||||
Ask the user: "Save this learning report to `.specify/optimize/learning-report-<date>.md`?"
|
||||
|
||||
If approved, save the full report for historical reference. This enables trend analysis across sessions: "Are the same patterns recurring despite rules being added?"
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Evidence-Based Only
|
||||
Every proposal cites specific files, line numbers, commits, and pattern counts. No speculative rules based on general best practices — only rules motivated by observed session behavior.
|
||||
|
||||
### Minimal Governance Growth
|
||||
Prefer memory entries (zero token cost to future sessions) over constitution rules (permanent token cost). Only propose constitution rules when the pattern is project-wide, tool-agnostic, and would benefit all future AI sessions.
|
||||
|
||||
### Deterministic Proposals
|
||||
Every proposed rule text is concrete, MUST/SHOULD qualified, and deterministic. If the AI agent writing the proposal cannot make the rule deterministic, it should propose a memory entry instead.
|
||||
|
||||
### Suggest-Only
|
||||
The learning report is a proposal, not an action. The user reviews each suggestion individually and decides what to keep. Declined proposals are preserved in the report for future reconsideration.
|
||||
|
||||
### Session Boundary Respect
|
||||
This command only analyzes the current session's work. It does not dig into older history or make suggestions based on past sessions. For historical analysis, use `/speckit.optimize.run` which audits the full constitution.
|
||||
357
.github/agents/speckit.optimize.run.agent.md
vendored
Normal file
357
.github/agents/speckit.optimize.run.agent.md
vendored
Normal file
@@ -0,0 +1,357 @@
|
||||
---
|
||||
description: Audit and optimize governance documents for AI context efficiency.
|
||||
handoffs:
|
||||
- label: Amend constitution
|
||||
agent: speckit.constitution
|
||||
prompt: Apply the approved optimization changes to the constitution
|
||||
- label: Verify consistency
|
||||
agent: speckit.analyze
|
||||
prompt: Verify cross-artifact consistency after governance changes
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: optimize -->
|
||||
<!-- Config: .specify/extensions/optimize/ -->
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
Arguments: `--category <name>` to run a single category, `--report-only` to skip the apply step.
|
||||
|
||||
## Goal
|
||||
|
||||
Audit an existing, populated constitution for problems that are **uniquely harmful in AI-driven development**: token bloat, stale rules, ambiguity causing non-deterministic behavior, redundant governance echoes, and incoherent structure. Produce a findings report with a concrete optimization plan. Apply **only** what the user explicitly approves.
|
||||
|
||||
This command does NOT author or amend the constitution (that is `/speckit.constitution`). It audits and optimizes existing content.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
- **Suggest-only**: NEVER modify any file without explicit user consent. Always present findings and a plan first, then ask before applying.
|
||||
- **Semantic preservation**: Optimization removes redundancy, not intent. Every governance rule must survive compression — only its expression changes.
|
||||
- **Spec-kit standard paths**: Use `.specify/memory/constitution.md` as the primary constitution path. If it contains a redirect (e.g., "Read and follow the constitution in `<path>`"), follow the redirect to the actual file. Fallback discovery order: `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`.
|
||||
- **Constitution authority**: Respect the constitution's own governance section. Version bumps follow its defined semver policy.
|
||||
- **Idempotency**: Running this command twice in succession on an optimized constitution MUST produce no new findings.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Locate and Load Constitution
|
||||
|
||||
Resolution order:
|
||||
1. Read `.specify/memory/constitution.md`
|
||||
2. If it contains a redirect pattern (e.g., `Read and follow the constitution in <path>`), follow the redirect to the actual file
|
||||
3. If `.specify/memory/constitution.md` does not exist, check fallbacks: `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`
|
||||
4. Abort with clear error if no constitution found
|
||||
|
||||
Validate the file is a populated constitution (not a raw template with `[PLACEHOLDER]` tokens). If it is still a template, advise the user to run `/speckit.constitution` first and abort.
|
||||
|
||||
Record the resolved file path as `CONSTITUTION_PATH` for all subsequent steps.
|
||||
|
||||
### 2. Load Configuration
|
||||
|
||||
Check for project config at `.specify/extensions/optimize/optimize-config.yml`. If not found, use `defaults` from `extension.yml`. Parse:
|
||||
- Which categories are enabled
|
||||
- Threshold values
|
||||
- Target context window size
|
||||
|
||||
### 3. Parse Constitution Structure
|
||||
|
||||
Extract and catalog:
|
||||
- **Sync Impact Report** (HTML comment at top) — version, dates, template status
|
||||
- **Version History** (HTML comment) — all version entries
|
||||
- **Title** (H1 heading)
|
||||
- **Core Principles** — for each: number, name, NON-NEGOTIABLE flag, individual rules as a flat list (each bullet, MUST/SHOULD statement, or table row with normative content)
|
||||
- **Quality Gates** table
|
||||
- **Governance** section — authority, amendment process, version semantics
|
||||
- **Version footer** — current version, ratified date, last amended date
|
||||
|
||||
Store each principle's rules as a flat list for cross-comparison.
|
||||
|
||||
### 4. Discover Governance Ecosystem
|
||||
|
||||
Scan for all governance files that AI agents may load:
|
||||
- `.specify/memory/constitution.md` (and its redirect target)
|
||||
- `CLAUDE.md` (root)
|
||||
- `AGENTS.md` (root)
|
||||
- `.github/copilot-instructions.md`
|
||||
- All files in `.ai/rules/` (if directory exists)
|
||||
- All files in `.specify/memory/` (if any beyond constitution)
|
||||
|
||||
For each file found, record: path, size in characters, estimated tokens (chars ÷ `chars_per_token`).
|
||||
|
||||
### 5. Run Analysis Categories
|
||||
|
||||
Run each enabled category. If `--category <name>` was provided, run only that one.
|
||||
|
||||
---
|
||||
|
||||
#### Category 1: Token Budget Analysis
|
||||
|
||||
*Why AI-specific*: AI agents pay the full token cost of the constitution on every single invocation. A 3000-token constitution across 50 daily sessions = 150K tokens/day of governance overhead. Humans skim; AI tokenizes everything.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Total token estimate**: Calculate chars ÷ `chars_per_token` for the constitution and each governance file discovered in Step 4.
|
||||
|
||||
2. **Per-section token breakdown**: For each H2/H3 section in the constitution, calculate its token cost and compute a "governance density" score = (number of distinct rules in section) ÷ (estimated tokens in section). Low density = high waste.
|
||||
|
||||
3. **Version history bloat**: Detect HTML comment blocks containing version history (pattern: `<!-- ... v\d+\.\d+\.\d+ ... -->`). These are valuable for humans reviewing the file but add zero governance value for AI agents. Measure their token cost.
|
||||
|
||||
4. **Anti-pattern tax**: Detect sections containing both "WRONG" / "Anti-Pattern" / "NEVER" code blocks AND "CORRECT" / "RIGHT" / "Correct Pattern" code blocks. The anti-pattern is often inferable from the correct pattern alone. Measure the token cost of each anti-pattern block.
|
||||
|
||||
5. **Inline code duplication**: For each fenced code block in the constitution, search the repository for matching files or near-matching code. If the code exists in the repo, it can be replaced with a file reference (e.g., "See `src/.../BeanConfiguration.java`"). Use glob/grep to find matching class names, method signatures, or patterns from the code block.
|
||||
|
||||
6. **Double-governance**: For each rule, check if an equivalent enforcement exists in:
|
||||
- Checkstyle config (glob for `**/checkstyle*.xml`)
|
||||
- Build tool config (glob for `build.gradle*`, `buildSrc/**`)
|
||||
- Dependency management (glob for `**/libs.versions.toml`, `**/pom.xml`)
|
||||
- CI pipeline config (glob for `.github/workflows/*`, `.pipelines/*`, `azure-pipelines*`)
|
||||
If a tool already enforces the rule, the constitution copy is redundant — it can be compressed to a reference.
|
||||
|
||||
7. **Prose-table overlap**: Detect when the same information appears in both prose (paragraph/bullets) and a table within the same H3 section. Measure the overlap token cost.
|
||||
|
||||
**Output per finding**: Section path, token cost, issue type, suggested fix, projected savings.
|
||||
|
||||
---
|
||||
|
||||
#### Category 2: Rule Health Analysis
|
||||
|
||||
*Why AI-specific*: AI agents have no institutional memory. A rule added 6 months ago for a one-time incident is enforced with the same authority as a core architectural principle. There is no natural "forgetting" mechanism — stale rules persist forever.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Incident-specific rules**: Detect rules that reference specific class names, method names, or file paths (backtick-wrapped identifiers like `` `ClassName` ``, `` `methodName` ``). Cross-reference: search the codebase for the named artifact. If it exists in only one component or has been removed, the rule may be too narrow for a project-wide constitution or entirely stale.
|
||||
|
||||
2. **Superseded rules**: Within the same principle and across principles, detect rules that govern the same domain at different specificity levels. Example: "no magic numbers" (general) + "use named constants for all numeric values" (specific) — the specific one supersedes the general.
|
||||
|
||||
3. **Graduated rules**: For each rule, check if it is fully enforced by automation:
|
||||
- Parse checkstyle config for matching check names (e.g., `MagicNumberCheck` → "no magic numbers" rule)
|
||||
- Check `buildSrc/` for custom Gradle tasks (e.g., `CheckFileHeaderTask` → "file headers required")
|
||||
- Check CI pipeline for quality gates
|
||||
If a rule is 100% enforced by tooling, the constitution statement is redundant and can be compressed to: "Enforced by [tool] — see `[config path]`."
|
||||
|
||||
4. **Stale rules via git history**: Run `git log --follow -p` on the constitution file. For rules introduced in older versions (check the version history comment block), evaluate whether the context that motivated the rule still applies. Flag rules that haven't been touched in >3 versions AND reference specific artifacts.
|
||||
|
||||
**Output per finding**: Rule text, principle location, health classification (CORE / OPERATIONAL / INCIDENT-RESPONSE / GRADUATED), recommendation, evidence.
|
||||
|
||||
---
|
||||
|
||||
#### Category 3: AI Interpretability Analysis
|
||||
|
||||
*Why AI-specific*: Ambiguity in the constitution causes non-deterministic behavior — different AI sessions resolve the same ambiguity differently, leading to inconsistent codebases. Rules that require human judgment are dead code to AI agents.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Unenforceable rules (require human action)**: Scan for rules containing: "check with", "discuss with", "team lead approval", "manual review", "consult", "ask before", "get sign-off". These are meaningful to humans but unactionable by AI agents.
|
||||
|
||||
2. **Ambiguous quantifiers**: Scan for rules containing: "appropriate", "reasonable", "sufficient", "proper", "clean", "good", "well-structured", "meaningful", "as needed", "where possible", "when necessary". These are interpreted differently by different AI models and sessions. For each, propose a concrete, deterministic replacement.
|
||||
|
||||
3. **Missing enforcement mechanism**: For each MUST rule, check if there is a corresponding automated enforcement (checkstyle, CI, Gradle task, spec-kit command). If a rule says MUST but nothing checks compliance, it is "aspirational governance" — effective only when the AI agent happens to remember it.
|
||||
|
||||
4. **Contradiction detection**: Parse all rules into normalized assertion form. Check for:
|
||||
- **Direct contradictions**: Rule A says "MUST X" and Rule B says "MUST NOT X" or implies not-X
|
||||
- **Indirect contradictions**: Rule A requires pattern P, Rule B requires pattern Q, where P and Q are mutually exclusive in practice
|
||||
- **Scope conflicts**: Two principles claim authority over the same domain with different guidance
|
||||
For each pair, assess severity: CRITICAL (direct), HIGH (indirect), MEDIUM (scope overlap).
|
||||
|
||||
5. **Implicit context dependencies**: Scan for rules referencing: "the team's convention", "our usual approach", "as discussed", "you know", "the standard pattern" (without specifying which). These rely on context that AI agents don't carry between sessions.
|
||||
|
||||
6. **Non-deterministic choice points**: Scan for rules with: "or" / "either...or" / "when appropriate" / "use your judgment" / "consider" that leave the resolution to the AI agent without a default. Each is a source of cross-session inconsistency.
|
||||
|
||||
**Output per finding**: Rule text, location, interpretability issue type, proposed deterministic rewrite, severity.
|
||||
|
||||
**Per-rule score** (0–100): Based on specificity (25), enforceability (25), determinism (25), self-containedness (25). Report average per principle and overall.
|
||||
|
||||
---
|
||||
|
||||
#### Category 4: Semantic Compression
|
||||
|
||||
*Why AI-specific*: 10 verbose rules that could be expressed as 2 concise rules cost 5× more context tokens for identical governance. This is not about human readability — it is about information density for context-limited AI consumers.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Collapsible rule clusters**: Group rules by semantic domain (testing, naming, architecture, dependencies, documentation). Within each group, identify rules that share a common parent assertion. Example: "No wildcard imports", "No magic numbers", "Explicit this. prefix", "JavaDoc required" are all checkstyle-enforced quality rules that could be collapsed to a single reference: "All code MUST pass checkstyle (`config/checkstyle/checkstyle.xml`) with zero violations." Measure per-cluster token savings.
|
||||
|
||||
2. **Inline-to-reference conversion**: For each fenced code block (identified in Cat 1), if the code exists as an actual file in the repo, propose replacing the inline block with a file reference. Example: 12 lines of `BeanConfiguration` Java code → "See `src/.../BeanConfiguration.java` for the canonical pattern." Measure per-block token savings.
|
||||
|
||||
3. **Redundant examples**: For sections containing both WRONG and CORRECT code blocks, evaluate whether the anti-pattern is inferable from the correct pattern and the rule text. If yes, the anti-pattern block can be removed. Measure savings.
|
||||
|
||||
4. **Table compression**: Detect tables where most cells follow a derivable pattern. Example: A 7-line Model Types table could be 3 lines of prose. Measure savings.
|
||||
|
||||
5. **Compressed constitution draft**: If total projected savings exceed 10%, produce a full compressed draft that preserves every governance rule while minimizing tokens. Include a "governance preservation check" listing every original rule and its location in the compressed version.
|
||||
|
||||
**Output per finding**: Original section, proposed replacement, token savings, governance preservation confirmation.
|
||||
|
||||
---
|
||||
|
||||
#### Category 5: Constitution Coherence
|
||||
|
||||
*Why AI-specific*: AI agents read the constitution linearly and assign roughly equal weight to all sections. A constitution that has grown organically through many amendments tends to be structurally unbalanced — one principle with 30 rules, another with 3. Related rules scattered across principles. Missing cross-references. No clear narrative arc. A human can mentally reorganize; an AI agent cannot.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Principle balance**: Count rules per principle (bullets, MUST/SHOULD statements, normative table rows). Flag if the largest principle has more than `principle_balance_ratio` (default: 3×) the rules of the smallest. Report the count per principle.
|
||||
|
||||
2. **Rule scatter**: For each rule, extract its semantic domain (testing, naming, architecture, dependencies, documentation, API, security). If rules from the same domain appear in more than one principle, flag as scattered. Example: naming conventions in Principle I + entity naming in Principle III = naming rules scattered.
|
||||
|
||||
3. **Missing cross-references**: Detect rules that reference concepts defined in other sections without an explicit cross-reference (e.g., a testing rule mentions "coverage" but coverage thresholds are in Quality Gates — no link between them).
|
||||
|
||||
4. **Orphaned sections**: Detect sections that are neither referenced by nor reference any other section. These may be bolt-on additions from specific AI sessions that were never integrated into the overall narrative.
|
||||
|
||||
5. **CLAUDE.md summary drift**: If `CLAUDE.md` exists and contains a "Critical Rules" or similar summary section, compare each rule against the constitution. Detect:
|
||||
- Rules in the summary missing from the constitution (orphaned summaries)
|
||||
- Rules in the constitution missing from the summary (under-documented)
|
||||
- Rules with wording differences between the two (drift)
|
||||
|
||||
**Output per finding**: Location, issue type, proposed resolution. Overall coherence score (0–100) based on balance (25), scatter (25), cross-referencing (25), drift (25).
|
||||
|
||||
---
|
||||
|
||||
#### Category 6: Governance Echo Detection
|
||||
|
||||
*Why AI-specific*: AI-driven projects accumulate multiple governance files — each loaded into the AI context. The same rule restated across files wastes tokens on every invocation and introduces contradiction risk when one copy is updated but others are not.
|
||||
|
||||
**Checks:**
|
||||
|
||||
1. **Cross-file rule duplication**: For each governance file discovered in Step 4, extract rules (bullets, MUST/SHOULD statements, normative table rows). Compare rules across all file pairs. Flag near-duplicates (same semantic intent, different wording).
|
||||
|
||||
2. **Summary drift**: Compare the main constitution against each governance file that summarizes it (typically `CLAUDE.md`). Detect rules updated in one but not the other.
|
||||
|
||||
3. **Redundant governance files**: If a governance file's rules are entirely a subset of the constitution's rules, the file is redundant. The entire file could be replaced with a pointer: "See `.specify/memory/constitution.md`."
|
||||
|
||||
4. **Governance chain depth**: Trace how the constitution is loaded by each AI tool. Count the number of governance documents in the loading chain and their cumulative token cost.
|
||||
|
||||
5. **Total governance budget**: Sum estimated tokens across all governance files. Express as a percentage of the target context window (from config). Flag if exceeding `governance_budget_percent` (default: 15%).
|
||||
|
||||
**Output per finding**: Source file, target file, duplicated rule text, recommendation. Overall governance echo map showing which files duplicate which rules.
|
||||
|
||||
---
|
||||
|
||||
### 6. Generate Unified Findings Report
|
||||
|
||||
Combine all category results into a single report. Present to the user:
|
||||
|
||||
```markdown
|
||||
## Governance Optimization: Findings Report
|
||||
|
||||
**Constitution**: <CONSTITUTION_PATH>
|
||||
**Current Version**: <version>
|
||||
**Estimated Tokens**: <total> (~<lines> lines)
|
||||
**Governance Ecosystem**: <file_count> files, <total_tokens> tokens (<percent>% of <context_window> context)
|
||||
|
||||
### Executive Summary
|
||||
|
||||
| Category | Findings | Severity | Projected Savings |
|
||||
|----------|----------|----------|-------------------|
|
||||
| Token Budget | X | <highest> | ~Y tokens |
|
||||
| Rule Health | X | <highest> | — |
|
||||
| AI Interpretability | X | <highest> | — |
|
||||
| Semantic Compression | X | <highest> | ~Y tokens |
|
||||
| Coherence | X | <highest> | — |
|
||||
| Governance Echo | X | <highest> | ~Y tokens |
|
||||
|
||||
**Overall Health Score**: X/100
|
||||
**Total Projected Token Reduction**: ~Y tokens (Z%)
|
||||
|
||||
### Top 5 Findings (by impact)
|
||||
|
||||
1. [Finding with highest token savings or highest severity]
|
||||
2. ...
|
||||
|
||||
### Detailed Findings
|
||||
|
||||
[Per-category details as described in each category's output section]
|
||||
```
|
||||
|
||||
### 7. Propose Optimization Plan
|
||||
|
||||
Based on findings, produce a concrete plan:
|
||||
|
||||
```markdown
|
||||
### Proposed Changes
|
||||
|
||||
| # | Change | Category | Files Affected | Token Impact | Risk |
|
||||
|---|--------|----------|----------------|--------------|------|
|
||||
| 1 | Remove version history HTML comments | Token Budget | constitution | -X tokens | Low |
|
||||
| 2 | Compress checkstyle rules to reference | Compression | constitution | -X tokens | Low |
|
||||
| ... | ... | ... | ... | ... | ... |
|
||||
|
||||
### Version Bump
|
||||
|
||||
- **Type**: PATCH / MINOR / MAJOR
|
||||
- **Rationale**: [why this bump level]
|
||||
- **New Version**: X.Y.Z
|
||||
|
||||
**Apply these changes?** Select which changes to apply, or approve all.
|
||||
```
|
||||
|
||||
Wait for user consent. Do NOT proceed without explicit approval.
|
||||
|
||||
### 8. Apply Approved Changes
|
||||
|
||||
For each user-approved change:
|
||||
|
||||
1. Apply the modification to `CONSTITUTION_PATH`
|
||||
2. Preserve the overall document structure (Sync Impact Report comment, version history, principles, quality gates, governance, footer)
|
||||
3. Update the version footer: bump per the semver rules in the constitution's governance section
|
||||
4. Update `Last Amended` date to today (ISO format YYYY-MM-DD)
|
||||
5. Add a new version history entry in the HTML comment block
|
||||
6. Update the Sync Impact Report HTML comment at the top
|
||||
|
||||
### 9. Post-Application Validation
|
||||
|
||||
After writing changes:
|
||||
1. Re-parse the updated constitution — verify no remaining `[PLACEHOLDER]` bracket tokens
|
||||
2. Verify version footer matches Sync Impact Report
|
||||
3. Verify all dates are ISO format (YYYY-MM-DD)
|
||||
4. Re-run a quick check on the output — verify no new contradictions or ambiguities were introduced by the edits
|
||||
5. Verify the total governance rule count has not decreased (compression changes expression, not intent)
|
||||
|
||||
### 10. Output Summary
|
||||
|
||||
```markdown
|
||||
## Governance Optimization Complete
|
||||
|
||||
**Version**: <old> → <new> (<bump-type>)
|
||||
**Constitution**: <CONSTITUTION_PATH>
|
||||
**Token Reduction**: <old_tokens> → <new_tokens> (<percent>% savings)
|
||||
|
||||
### Changes Applied
|
||||
- [List of applied changes with token impact]
|
||||
|
||||
### Changes Declined
|
||||
- [List of user-declined changes, preserved for next run]
|
||||
|
||||
### Sync Impact Report Updated
|
||||
- Version change: <old> → <new>
|
||||
- Modified sections: [list]
|
||||
- Templates status: [all aligned / needs review]
|
||||
|
||||
### Suggested Commit Message
|
||||
docs: optimize constitution to v<new> — reduce governance token overhead by <percent>%
|
||||
|
||||
### Recommended Follow-Up
|
||||
- Review updated constitution for accuracy
|
||||
- Run `/speckit.constitution` if substantive amendments are needed beyond optimization
|
||||
- Run `/speckit.analyze` to verify cross-artifact consistency
|
||||
- Run `/speckit.optimize.tokens` to verify ecosystem-wide token budget
|
||||
```
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Suggest-Only
|
||||
Every change is proposed, never applied silently. The user has full veto power over every individual finding. "Apply all" is offered as a convenience but never the default.
|
||||
|
||||
### Semantic Preservation
|
||||
Optimization MUST NOT change the meaning of any rule. Compression removes redundancy in expression, not in intent. After optimization, every governance rule that existed before MUST still be expressible from the optimized document.
|
||||
|
||||
### Constitution Authority
|
||||
The review respects the constitution's own governance section. Version bumps follow the defined semver policy. If the governance section specifies an amendment process, the optimization follows it.
|
||||
|
||||
### Idempotency
|
||||
Running this command twice in succession on the same constitution MUST produce zero new findings on the second run. If it does not, there is a bug in the optimization logic.
|
||||
|
||||
### Context Efficiency
|
||||
The primary goal is making the constitution cheaper to include in AI context windows while maintaining full governance clarity. Every recommendation must be justified by a concrete token savings figure or a measurable improvement in AI interpretability.
|
||||
201
.github/agents/speckit.optimize.tokens.agent.md
vendored
Normal file
201
.github/agents/speckit.optimize.tokens.agent.md
vendored
Normal file
@@ -0,0 +1,201 @@
|
||||
---
|
||||
description: Track and report token usage across extensions and governance files.
|
||||
handoffs:
|
||||
- label: Optimize governance
|
||||
agent: speckit.optimize.run
|
||||
prompt: Run a full governance audit to reduce token overhead
|
||||
- label: Amend constitution
|
||||
agent: speckit.constitution
|
||||
prompt: Apply approved token-reduction changes to the constitution
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: optimize -->
|
||||
<!-- Config: .specify/extensions/optimize/ -->
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
Arguments: `--diff` to compare against the previous report, `--extensions-only` to skip governance files.
|
||||
|
||||
## Goal
|
||||
|
||||
Measure the token footprint of every governance document and extension command that AI agents load during sessions. Produce a token usage report with per-file costs, per-extension rankings, session load estimates, and historical trends. Suggest optimizations but apply **nothing** without user consent.
|
||||
|
||||
This command answers: "How much of my AI context window is consumed by governance and tooling overhead before any actual work begins?"
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
- **Suggest-only**: NEVER modify any file without explicit user consent. This command is read-only by default.
|
||||
- **Spec-kit standard paths**: Start from `.specify/` as the source of truth. Discover tool-specific files (`CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`) by checking if they exist.
|
||||
- **Reproducible estimates**: Token estimation uses chars ÷ `chars_per_token` (default: 4.0, configurable). Note this is approximate — actual tokenizer counts vary by model. Lower ratios (3.0–3.5) give more conservative estimates for code-heavy files.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Discover Governance Files
|
||||
|
||||
Scan for all files that AI agents may load on session start or command invocation:
|
||||
|
||||
**Always-loaded files** (loaded on every AI session):
|
||||
- `CLAUDE.md` (if present — Claude Code sessions)
|
||||
- `AGENTS.md` (if present — generic agent sessions)
|
||||
- `.github/copilot-instructions.md` (if present — Copilot sessions)
|
||||
|
||||
**Constitution chain**:
|
||||
- `.specify/memory/constitution.md` — read to check if it is a redirect or contains content
|
||||
- If redirect, follow to the actual file (e.g., `.ai/rules/constitution.md`)
|
||||
- Record both the pointer and the target
|
||||
|
||||
**Supplementary governance files**:
|
||||
- Glob `.ai/rules/*.md` (if directory exists)
|
||||
- Glob `.specify/memory/*.md` (beyond constitution)
|
||||
- Any other files referenced from the always-loaded files (parse for markdown links and "Read and follow" patterns)
|
||||
|
||||
For each file: record path, exists (bool), size in bytes, size in characters, estimated tokens (chars ÷ `chars_per_token`).
|
||||
|
||||
### 2. Inventory Extension Commands
|
||||
|
||||
For each extension listed in `.specify/extensions.yml` → `installed:`:
|
||||
|
||||
1. Read `.specify/extensions/<ext-id>/extension.yml`
|
||||
2. For each command in `provides.commands[]`:
|
||||
- Locate the command file (the `file:` field points to the source)
|
||||
- Measure its character count and estimated tokens
|
||||
3. Sum total tokens per extension
|
||||
|
||||
Produce a ranked list of extensions by total token footprint.
|
||||
|
||||
### 3. Calculate Per-Session Load Estimates
|
||||
|
||||
Estimate what gets loaded for different session types:
|
||||
|
||||
**Baseline session** (always loaded):
|
||||
- Sum tokens of always-loaded governance files
|
||||
- This is the minimum overhead before any work begins
|
||||
|
||||
**Constitution-aware session** (baseline + constitution):
|
||||
- Add constitution chain tokens
|
||||
- Add supplementary governance file tokens
|
||||
|
||||
**Command invocation** (per command):
|
||||
- For each extension command, the cost is: baseline + command file tokens + any files the command references (parse "Read" / "Load" instructions in the command file)
|
||||
|
||||
Present estimates for each context window size in `context_window_sizes` config (default: 8K, 32K, 128K, 200K, 1M).
|
||||
|
||||
```markdown
|
||||
### Per-Session Token Budget
|
||||
|
||||
| Session Type | Tokens | % of 8K | % of 32K | % of 128K | % of 200K | % of 1M |
|
||||
|---|---|---|---|---|---|---|
|
||||
| Baseline (governance only) | X | X% | X% | X% | X% | X% |
|
||||
| + Constitution | X | X% | X% | X% | X% | X% |
|
||||
| + Largest command | X | X% | X% | X% | X% | X% |
|
||||
```
|
||||
|
||||
### 4. Historical Trend Analysis
|
||||
|
||||
Check for a previous report at `.specify/optimize/token-report.md`.
|
||||
|
||||
If found:
|
||||
- Parse the previous report's per-file token counts
|
||||
- Compare each file: current vs previous
|
||||
- Calculate per-file growth/reduction
|
||||
- Flag files growing faster than `file_growth_percent` threshold (default: 20%)
|
||||
- Show overall governance token trend (growing / stable / shrinking)
|
||||
|
||||
If not found:
|
||||
- Note this is the first run — no trend data available
|
||||
- Recommend running periodically to track trends
|
||||
|
||||
### 5. Generate Token Usage Report
|
||||
|
||||
Present the full report to the user:
|
||||
|
||||
```markdown
|
||||
## Token Usage Report
|
||||
|
||||
**Date**: <ISO date>
|
||||
**Target Context Window**: <from config> tokens
|
||||
|
||||
### Governance Files
|
||||
|
||||
| File | Exists | Chars | Est. Tokens | Load Timing | Notes |
|
||||
|---|---|---|---|---|---|
|
||||
| CLAUDE.md | Yes/No | X | X | Always | — |
|
||||
| .specify/memory/constitution.md | Yes/No | X | X | Always | Redirect to <path> |
|
||||
| <actual constitution path> | Yes | X | X | Always | Actual content |
|
||||
| AGENTS.md | Yes/No | X | X | Always | — |
|
||||
| .github/copilot-instructions.md | Yes/No | X | X | Always | — |
|
||||
| .ai/rules/<file>.md | Yes | X | X | On reference | — |
|
||||
|
||||
**Total governance tokens**: X (~Y% of <context_window>)
|
||||
|
||||
### Extension Commands (ranked by token cost)
|
||||
|
||||
| Extension | Commands | Total Tokens | Largest Command | Largest Tokens |
|
||||
|---|---|---|---|---|
|
||||
| <ext-id> | X | X | <cmd> | X |
|
||||
| ... | ... | ... | ... | ... |
|
||||
|
||||
**Total extension tokens**: X (loaded per invocation, not per session)
|
||||
|
||||
### Per-Session Estimates
|
||||
|
||||
[Table from Step 3]
|
||||
|
||||
### Historical Trend
|
||||
|
||||
| File | Previous | Current | Change | Growth % | Flag |
|
||||
|---|---|---|---|---|---|
|
||||
| <path> | X | X | +/-X | X% | [!] if > threshold |
|
||||
|
||||
**Overall governance trend**: Growing / Stable / Shrinking (X% change)
|
||||
|
||||
### Optimization Suggestions
|
||||
|
||||
[Ranked by projected token savings — suggest only, do not apply]
|
||||
|
||||
1. **<suggestion>**: <description> — saves ~X tokens
|
||||
2. ...
|
||||
```
|
||||
|
||||
### 6. Save Report
|
||||
|
||||
Ask the user: "Save this report to `.specify/optimize/token-report.md` for trend tracking?"
|
||||
|
||||
If approved:
|
||||
- Write the report to `.specify/optimize/token-report.md` (create directory if needed)
|
||||
- This enables historical trend comparison on future runs
|
||||
|
||||
If declined:
|
||||
- Report is displayed in conversation only, not persisted
|
||||
|
||||
### 7. Suggest Next Steps
|
||||
|
||||
Based on findings:
|
||||
|
||||
```markdown
|
||||
### Recommended Actions
|
||||
|
||||
- If governance budget exceeds threshold → suggest `/speckit.optimize.run` for full audit
|
||||
- If specific extensions are oversized → suggest reviewing those command files for compression
|
||||
- If CLAUDE.md duplicates constitution → suggest consolidation
|
||||
- If growth trend is upward → suggest scheduling periodic token audits
|
||||
```
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Read-Only Default
|
||||
This command reads and measures — it does not modify. The only write action is saving the report file, and only with explicit consent.
|
||||
|
||||
### Consistent Estimation
|
||||
Token counts use chars ÷ `chars_per_token` (configurable, default: 4.0) throughout. This is an approximation — actual counts vary by tokenizer. Use 3.0–3.5 for code-heavy projects, 4.0 for prose-heavy. The approximation is consistent across runs, making trend analysis valid even if absolute numbers are approximate.
|
||||
|
||||
### Actionable Output
|
||||
Every metric in the report is paired with a concrete action: "X tokens in version history → remove via `/speckit.optimize.run`". Raw numbers without actions are noise.
|
||||
|
||||
### Trend Over Snapshots
|
||||
A single run provides a snapshot. Repeated runs provide a trend. The historical comparison is the most valuable output — it tells you whether your governance is growing, stable, or shrinking over time.
|
||||
219
.github/agents/speckit.verify.run.agent.md
vendored
Normal file
219
.github/agents/speckit.verify.run.agent.md
vendored
Normal file
@@ -0,0 +1,219 @@
|
||||
---
|
||||
description: Perform a non-destructive post-implementation verification gate validating
|
||||
the implementation against spec.md, plan.md, tasks.md, and constitution.md.
|
||||
scripts:
|
||||
sh: .specify/scripts/bash/check-prerequisites.sh --json --paths-only
|
||||
ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly
|
||||
---
|
||||
|
||||
|
||||
<!-- Extension: verify -->
|
||||
<!-- Config: .specify/extensions/verify/ -->
|
||||
## User Input
|
||||
|
||||
```text
|
||||
$ARGUMENTS
|
||||
```
|
||||
|
||||
You **MUST** consider the user input before proceeding (if not empty).
|
||||
|
||||
## Goal
|
||||
|
||||
Validate the implementation against its specification artifacts (`spec.md`, `plan.md`, `tasks.md`, `constitution.md`). This command MUST run only after `/speckit.implement` has completed.
|
||||
|
||||
## Operating Constraints
|
||||
|
||||
**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
|
||||
|
||||
**Constitution Authority**: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this verification scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, tasks or implementation—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/speckit.verify.run`.
|
||||
|
||||
## Execution Steps
|
||||
|
||||
### 1. Initialize Verification Context
|
||||
|
||||
Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root.
|
||||
|
||||
1. **Script succeeds** (on a feature branch): Parse JSON for FEATURE_DIR. Set `FEATURE_BRANCH = true`. Proceed to next step.
|
||||
2. **Script fails** (not on a feature branch): You MUST prompt for available features (Scan `specs/NNN-*/` to get available features). Use the **AskUserQuestion tool** to let the user select. **Do NOT guess or auto-select a change. Always let the user choose.**
|
||||
|
||||
Derive absolute paths:
|
||||
|
||||
- SPEC = FEATURE_DIR/spec.md
|
||||
- PLAN = FEATURE_DIR/plan.md
|
||||
- TASKS = FEATURE_DIR/tasks.md.
|
||||
|
||||
Abort if any required file is missing (instruct the user to run missing prerequisite command).
|
||||
For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").
|
||||
|
||||
### 2. Load Configuration
|
||||
|
||||
Run the load-config script (`.specify/extensions/verify/scripts/bash/load-config.sh` or `.specify/extensions/verify/scripts/powershell/load-config.ps1`) from the repo root. Parse the `max_findings` value from its output and store it for use in Step 6. If the script fails, abort and relay its error message to the user.
|
||||
|
||||
### 3. Load Artifacts (Progressive Disclosure)
|
||||
|
||||
Load only the minimal necessary context from each artifact:
|
||||
|
||||
**From spec.md:**
|
||||
|
||||
- User Scenarios & Testing (user stories, acceptance scenarios, priorities)
|
||||
- Edge Cases
|
||||
- Functional Requirements
|
||||
- Success Criteria / Measurable Outcomes (performance, security, availability, observability targets)
|
||||
- Assumptions
|
||||
|
||||
**From plan.md:**
|
||||
|
||||
- Architecture/stack choices
|
||||
- Technical constraints
|
||||
- Technical Context (language, dependencies, storage, testing, platform, constraints)
|
||||
- Project Structure (documentation layout and source code layout)
|
||||
|
||||
**From data-model.md (if present):**
|
||||
|
||||
- Entity names, fields, and relationships
|
||||
- Validation rules
|
||||
- State transitions
|
||||
|
||||
**From tasks.md:**
|
||||
|
||||
- Task IDs
|
||||
- Completion status
|
||||
- Descriptions
|
||||
- Phase grouping
|
||||
- Referenced file paths
|
||||
|
||||
**From constitution:**
|
||||
|
||||
- Load `.specify/memory/constitution.md` for principle validation
|
||||
|
||||
### 4. Identify Implementation Scope
|
||||
|
||||
Build the set of files to verify from tasks.md.
|
||||
|
||||
- Parse all tasks in tasks.md — both completed (`[x]`/`[X]`) and incomplete (`[ ]`)
|
||||
- Extract file paths referenced in each task description
|
||||
- Build **REVIEW_FILES** set from completed task file paths
|
||||
- Track **INCOMPLETE_TASK_FILES** from incomplete tasks (used by check C)
|
||||
|
||||
### 5. Build Semantic Models
|
||||
|
||||
Create internal representations (do not include raw artifacts in output):
|
||||
|
||||
- **Task inventory**: Each task with ID, completion status, referenced file paths, and phase grouping
|
||||
- **Implementation mapping**: Map each completed task to its referenced file paths
|
||||
- **File inventory**: All REVIEW_FILES with existence verification — flag any task-referenced file that does not exist on disk
|
||||
- **Requirements inventory**: Each functional requirement with a stable key — map to tasks and REVIEW_FILES for implementation evidence (evidence = file in REVIEW_FILES containing keyword/ID match, function signatures, or code paths that address the requirement)
|
||||
- **Spec intent references**: User stories, acceptance criteria, scenarios, edge cases, and code-verifiable success criteria from spec.md
|
||||
- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements
|
||||
|
||||
### 6. Verification Checks (Token-Efficient Analysis)
|
||||
|
||||
Focus on high-signal findings. **Limit to the configured `max_findings` value** (loaded in Step 2); aggregate remainder in overflow summary.
|
||||
|
||||
#### A. Task Completion
|
||||
|
||||
- Compare completed (`[x]`/`[X]`) vs total tasks
|
||||
- Flag majority incomplete vs minority incomplete
|
||||
|
||||
#### B. File Existence
|
||||
|
||||
- Task-referenced files that do not exist on disk
|
||||
- Tasks referencing ambiguous or unresolvable paths
|
||||
|
||||
#### C. Requirement Coverage
|
||||
|
||||
- Requirements with no implementation evidence in REVIEW_FILES
|
||||
- Requirements whose tasks are all incomplete
|
||||
|
||||
#### D. Scenario & Test Coverage
|
||||
|
||||
- Spec scenarios with no corresponding test or code path
|
||||
- Edge cases with no corresponding test, guard clause, or error-handling code path
|
||||
- No test files detected at all in REVIEW_FILES
|
||||
|
||||
#### E. Spec Intent Alignment
|
||||
|
||||
- Implementation diverging from spec intent (minor vs fundamental divergence)
|
||||
- Compare acceptance criteria against actual behaviour in REVIEW_FILES
|
||||
- Code-verifiable success criteria (performance, security, availability, observability) with no evidence of implementation support — skip business/UX metrics that require post-deployment measurement
|
||||
|
||||
#### F. Constitution Alignment
|
||||
|
||||
- Any implementation element conflicting with a constitution MUST principle
|
||||
- Missing mandated sections or quality gates from constitution
|
||||
|
||||
#### G. Design & Structure Consistency
|
||||
|
||||
- Architectural decisions or design patterns from plan.md not reflected in code
|
||||
- Planned directory/file layout deviating from actual structure
|
||||
- New code deviating from existing project conventions (naming, module structure, error handling patterns)
|
||||
- Public APIs/exports/endpoints not described in plan.md
|
||||
|
||||
### 7. Severity Assignment
|
||||
|
||||
Use this heuristic to prioritize findings:
|
||||
|
||||
- **CRITICAL**: Violates constitution MUST, majority of tasks incomplete, task-referenced files missing from disk, requirement with zero implementation
|
||||
- **HIGH**: Spec intent divergence, fundamental implementation mismatch with acceptance criteria, missing scenario/test coverage
|
||||
- **MEDIUM**: Design pattern drift, minor spec intent deviation
|
||||
- **LOW**: Structure deviations, naming inconsistencies, minor observations not affecting functionality
|
||||
|
||||
### 8. Produce Compact Verification Report
|
||||
|
||||
Output a Markdown report (no file writes) with the following structure.
|
||||
|
||||
**If `FEATURE_BRANCH = false`**, prepend: `> ⚠️ **Non-Feature-Branch Verification** from \`<BRANCH>\` against \`<FEATURE_DIR>\`. Some checks may be affected by cross-feature interference.`
|
||||
|
||||
## Verification Report
|
||||
|
||||
| ID | Category | Severity | Location(s) | Summary | Recommendation |
|
||||
|----|----------|----------|-------------|---------|----------------|
|
||||
| A1 | Task Completion | CRITICAL | tasks.md | 3 of 12 tasks incomplete | Complete tasks T05, T08, T11 |
|
||||
| B1 | File Existence | CRITICAL | src/auth.ts | Task-referenced file missing | Create file or update task reference |
|
||||
| C1 | Requirement Coverage | CRITICAL | spec.md:FR-003 | No implementation evidence | Implement FR-003 |
|
||||
|
||||
(Add one row per finding; generate stable IDs prefixed by check letter: A1, B1, C1... Reference specific files and line numbers in Location(s) where applicable.)
|
||||
|
||||
**Task Summary Table:**
|
||||
|
||||
| Task ID | Status | Referenced Files | Notes |
|
||||
|---------|--------|-----------------|-------|
|
||||
|
||||
**Constitution Alignment Issues:** (if any)
|
||||
|
||||
**Metrics:**
|
||||
|
||||
- Total Tasks (completed / total)
|
||||
- Requirement Coverage % (requirements with implementation evidence / total)
|
||||
- Files Verified
|
||||
- Critical Issues Count
|
||||
|
||||
### 9. Provide Next Actions
|
||||
|
||||
At end of report, output a concise Next Actions block:
|
||||
|
||||
- If CRITICAL issues exist: Recommend resolving before proceeding
|
||||
- If HIGH issues exist: Recommend addressing before merge; user may proceed at own risk
|
||||
- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions
|
||||
- Provide explicit command suggestions: e.g., "Run `/speckit.implement` to address findings and re-run verification", "Implementation verified — ready for review or merge"
|
||||
|
||||
### 10. Offer Remediation
|
||||
|
||||
Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
|
||||
|
||||
## Operating Principles
|
||||
|
||||
### Context Efficiency
|
||||
|
||||
- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation
|
||||
- **Progressive disclosure**: Load artifacts and source files incrementally; don't dump all content into analysis
|
||||
- **Token-efficient output**: Limit findings table to the configured `max_findings` value; summarize overflow
|
||||
- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts
|
||||
|
||||
### Analysis Guidelines
|
||||
|
||||
- **NEVER modify files** (this is read-only analysis)
|
||||
- **NEVER hallucinate missing sections** (if absent, report them accurately)
|
||||
- **Prioritize constitution violations** (these are always CRITICAL)
|
||||
- **Use examples over exhaustive rules** (cite specific instances, not generic patterns)
|
||||
- **Report zero issues gracefully** (emit success report with coverage statistics)
|
||||
124
.github/copilot-instructions.md
vendored
124
.github/copilot-instructions.md
vendored
@@ -1,5 +1,7 @@
|
||||
# Meshtastic Android — Copilot Instructions
|
||||
|
||||
> **Full rules**: `AGENTS.md` is the source of truth. This file is a compact quick-reference for build commands and task naming. For architecture, conventions, and workflow details, consult `AGENTS.md` and the `.skills/` playbooks listed at the bottom.
|
||||
|
||||
## Build, Test & Lint
|
||||
|
||||
**Requires:** JDK 21, `ANDROID_HOME` set, proto submodule initialized.
|
||||
@@ -42,118 +44,20 @@ KMP modules have different task names than pure-Android modules. Using the wrong
|
||||
- ❌ `:feature:connections:testDebugUnitTest` — ambiguous in KMP modules. Use `:feature:connections:allTests`.
|
||||
- ❌ `:feature:connections:compileFdroidDebugKotlin` — wrong for KMP. Use `:feature:connections:compileKotlinJvm` or `kmpSmokeCompile`.
|
||||
|
||||
## Architecture
|
||||
## Quick Reference
|
||||
|
||||
**Kotlin Multiplatform** project targeting Android, Desktop (JVM), and iOS. Business logic lives in `commonMain`; platform shells (`app/`, `desktop/`) wire DI and host UI.
|
||||
- **Architecture**: KMP project (Android, Desktop, iOS). Business logic in `commonMain`; platform shells (`app/`, `desktop/`) wire DI and host UI. See `AGENTS.md` and `.skills/kmp-architecture/`.
|
||||
- **Flavors**: `fdroid` (OSS) / `google` (Maps + DataDog). Only one installable at a time (different signing keys).
|
||||
- **Verify before push**: Run `./gradlew spotlessApply detekt assembleDebug test allTests`, then confirm CI with `gh pr checks <PR>`.
|
||||
- **Strings**: `stringResource(Res.string.key)` — run `python3 scripts/sort-strings.py` after adding strings.
|
||||
- **Icons**: `MeshtasticIcons` (from `core/ui/icon/`), not `material.icons.Icons`.
|
||||
- **Error handling**: `safeCatching {}` (not `runCatching {}`) in coroutine code.
|
||||
- **Dispatchers**: `org.meshtastic.core.common.util.ioDispatcher`, not `Dispatchers.IO`.
|
||||
- **Navigation**: `MeshtasticNavDisplay` + `NavigationBackHandler` (not Android `BackHandler`).
|
||||
- **Protos**: `core/proto/` is a read-only git submodule. Never modify proto files.
|
||||
- **Branches**: Must start with `feat/`, `fix/`, `chore/`, `docs/`, `build/`, `ci/`, `refactor/`, `test/`, `deps/`, or a numeric spec prefix. Always branch off `origin/main`.
|
||||
|
||||
### Module layers
|
||||
|
||||
| Layer | Modules | Role |
|
||||
|-------|---------|------|
|
||||
| Host | `app`, `desktop` | Platform shell, Koin root, theme |
|
||||
| Feature | `feature/*` | Self-contained screens (KMP, `meshtastic.kmp.feature` plugin) |
|
||||
| Core | `core/*` | Shared logic, data, networking, UI components |
|
||||
|
||||
### Key technologies
|
||||
|
||||
- **UI:** Compose Multiplatform + Material 3 Adaptive
|
||||
- **Navigation:** JetBrains Navigation 3 (`@Serializable sealed interface` routes in `core:navigation`)
|
||||
- **DI:** Koin 4.2+ with K2 Compiler Plugin (`@Module`, `@KoinViewModel`, `startKoin<AndroidKoinApp>`)
|
||||
- **Networking:** Ktor (no OkHttp)
|
||||
- **BLE:** Kable (via `core:ble`)
|
||||
- **Database:** Room KMP
|
||||
- **I/O:** Okio
|
||||
- **Build:** Gradle Kotlin DSL with convention plugins in `build-logic/`
|
||||
- **Flavors:** `fdroid` (OSS) / `google` (Maps + DataDog)
|
||||
|
||||
### Navigation pattern
|
||||
|
||||
Feature navigation graphs are extension functions on `EntryProviderScope<NavKey>` in `commonMain`. The host shell renders via `MeshtasticNavDisplay`. Use `NavigationBackHandler` (not Android's `BackHandler`).
|
||||
|
||||
## Key Conventions
|
||||
|
||||
### Source-set boundaries
|
||||
|
||||
- **`commonMain`** — All business logic, ViewModels, UI. No `java.*` or `android.*` imports.
|
||||
- **`androidMain`** — Android framework integration only. No business logic.
|
||||
- **`jvmMain` / `jvmAndroidMain`** — Shared JVM code (Android + Desktop).
|
||||
- Platform capabilities: prefer interface + DI over `expect`/`actual`.
|
||||
|
||||
### Strings & formatting
|
||||
|
||||
- All strings in `core/resources/src/commonMain/composeResources/values/strings.xml`
|
||||
- Use `stringResource(Res.string.key)` — never hardcoded strings.
|
||||
- CMP only supports `%N$s` (string) and `%N$d` (int) — pre-format floats with `NumberFormatter.format()`.
|
||||
- Run `python3 scripts/sort-strings.py` after adding strings.
|
||||
|
||||
### Error handling
|
||||
|
||||
- Use `safeCatching {}` (from `core:common`) instead of `runCatching {}` in suspend/coroutine code — `runCatching` swallows `CancellationException`.
|
||||
|
||||
### Dispatchers
|
||||
|
||||
- Use `org.meshtastic.core.common.util.ioDispatcher` — never `Dispatchers.IO` directly.
|
||||
- Inject `CoroutineDispatchers` from `core:di`.
|
||||
|
||||
### Build-logic
|
||||
|
||||
- Convention plugins: `meshtastic.kmp.feature`, `meshtastic.kmp.library`, `meshtastic.kmp.jvm.android`, `meshtastic.koin`
|
||||
- Use `libs.library("alias-name")` string-based lookups (not type-safe accessors) in convention plugins.
|
||||
- Prefer lazy Gradle configuration (`configureEach`, `withPlugin`, provider APIs).
|
||||
|
||||
### Icons
|
||||
|
||||
- Use `MeshtasticIcons` (from `core/ui/icon/`) instead of `material.icons.Icons`.
|
||||
|
||||
### Protos
|
||||
|
||||
- `core/proto/` is a **read-only git submodule** from `meshtastic/protobufs`. Never modify proto files.
|
||||
|
||||
### Design standards
|
||||
|
||||
- All UI must conform to the [Meshtastic Client Design Standards](https://raw.githubusercontent.com/meshtastic/design/refs/heads/master/standards/meshtastic_design_standards_latest.md).
|
||||
- Review new screens/significant UI changes against the standards before merge.
|
||||
|
||||
### Branch naming
|
||||
|
||||
Branches must start with: `bugfix/`, `enhancement/`, `dependencies/`, or `repo/`.
|
||||
|
||||
### Branching workflow
|
||||
|
||||
- `origin` = `meshtastic/Meshtastic-Android` (upstream, source of truth). Personal forks are typically behind.
|
||||
- Always create branches off fetched upstream: `git fetch origin && git checkout -b <name> origin/main`
|
||||
- Never branch from a personal fork's `main` — it may be stale.
|
||||
|
||||
### Push workflow (verify-then-push)
|
||||
|
||||
**Before push:**
|
||||
```bash
|
||||
./gradlew spotlessApply detekt assembleDebug test allTests # or targeted module tasks
|
||||
```
|
||||
Only push when the above passes locally.
|
||||
|
||||
**After push:**
|
||||
```bash
|
||||
gh pr checks <PR_NUMBER> # or: gh run list --branch <branch> --limit 3
|
||||
```
|
||||
Report CI status only after fetching actual results. Never say "CI should be green now" — check and confirm.
|
||||
|
||||
### Scope discipline
|
||||
|
||||
When a working branch grows beyond ~5 logical commits or starts spanning unrelated concerns, proactively propose:
|
||||
1. A fresh branch off `origin/main`
|
||||
2. Cherry-pick only the high-impact, low-blast-radius changes
|
||||
3. Defer tangential work to follow-up PRs
|
||||
|
||||
Don't pile unrelated changes onto an existing branch. Squash fixup commits before pushing.
|
||||
|
||||
### Multi-flavor device installs
|
||||
|
||||
Two app flavors exist: `com.geeksville.mesh` (fdroid) and `com.geeksville.mesh.google` (google). Only one can be installed at a time (different signing keys). When switching flavors on a device:
|
||||
- Uninstall the other flavor first, or the install will fail silently.
|
||||
- Be aware that uninstalling loses onboarding state, permissions, and bonded-device data. Ask before uninstalling if the user has an active session.
|
||||
|
||||
## Deeper guidance
|
||||
## Deeper Guidance
|
||||
|
||||
Consult `.skills/` for detailed playbooks:
|
||||
- `.skills/project-overview/` — Full codebase map and bootstrap
|
||||
|
||||
3
.github/prompts/speckit.brownfield.bootstrap.prompt.md
vendored
Normal file
3
.github/prompts/speckit.brownfield.bootstrap.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.brownfield.bootstrap
|
||||
---
|
||||
3
.github/prompts/speckit.brownfield.migrate.prompt.md
vendored
Normal file
3
.github/prompts/speckit.brownfield.migrate.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.brownfield.migrate
|
||||
---
|
||||
3
.github/prompts/speckit.brownfield.scan.prompt.md
vendored
Normal file
3
.github/prompts/speckit.brownfield.scan.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.brownfield.scan
|
||||
---
|
||||
3
.github/prompts/speckit.brownfield.validate.prompt.md
vendored
Normal file
3
.github/prompts/speckit.brownfield.validate.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.brownfield.validate
|
||||
---
|
||||
3
.github/prompts/speckit.optimize.learn.prompt.md
vendored
Normal file
3
.github/prompts/speckit.optimize.learn.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.optimize.learn
|
||||
---
|
||||
3
.github/prompts/speckit.optimize.run.prompt.md
vendored
Normal file
3
.github/prompts/speckit.optimize.run.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.optimize.run
|
||||
---
|
||||
3
.github/prompts/speckit.optimize.tokens.prompt.md
vendored
Normal file
3
.github/prompts/speckit.optimize.tokens.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.optimize.tokens
|
||||
---
|
||||
3
.github/prompts/speckit.verify.run.prompt.md
vendored
Normal file
3
.github/prompts/speckit.verify.run.prompt.md
vendored
Normal file
@@ -0,0 +1,3 @@
|
||||
---
|
||||
agent: speckit.verify.run
|
||||
---
|
||||
Reference in New Issue
Block a user