Skip to content

feat: Add algorithm documentation for robotics, ML, scientific computation, graphics, game dev #321

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ajaygunalan wants to merge 1 commit into
base: main
Choose a base branch
from
+279 −0
Open

feat: Add algorithm documentation for robotics, ML, scientific computation, graphics, game dev #321

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
179 changes: 179 additions & 0 deletions commands/agent-os/algorithm-drift.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,179 @@
# Algorithm Drift

Detect drift between algorithm documentation and implementation code.

This command compares an algorithm spec in `agent-os/standards/algorithms/` against its owned implementation files to find mismatches in conventions, parameters, or structure.

---

## When to Use

- After modifying algorithm implementation code
- Before major refactors of mathematical code
- When debugging convention-related bugs (wrong frames, units, quaternions)
- Periodic sync checks for algorithm-heavy projects

---

## Process

### Step 1: Identify the Algorithm

If the user specifies an algorithm name (e.g., `/algorithm-drift ekf`), use it directly.

If no name provided, list available algorithms:

```bash
ls agent-os/standards/algorithms/*.md
```

Use `AskUserQuestion` to let user select which algorithm to check.

### Step 2: Read the Algorithm Spec

Read the algorithm spec file at `agent-os/standards/algorithms/{name}.md`.

Parse the frontmatter to extract the `owns:` field listing implementation files.

**owns: field rules:**
- Paths are relative to project root
- Globs are supported (e.g., `src/filters/*.py`)
- If a file is missing, report as warning (not error)

### Step 3: Read Owned Implementation Files

For each path in `owns:`:
- Expand globs if present
- Read each file
- If file missing, note it as warning

### Step 4: Compare Spec vs Code

Analyze for four types of drift:

1. **Structural drift**: Functions present/missing, different step order than spec
2. **Parameter drift**: Different I/O signatures, changed constants
3. **Mathematical drift**: Different equations, changed conventions (frames, quaternions, units)
4. **Implementation drift**: Refactored code, new files not listed in `owns:`

Focus especially on the **Conventions** section — this is where silent bugs hide.

### Step 5: Report Findings

If no drift detected:
```
No drift detected in agent-os/standards/algorithms/{name}.md

Checked files:
- src/filters/ekf.ts (ok)
- src/filters/ekf.test.ts (ok)
```

If drift detected:
```
Drift detected in agent-os/standards/algorithms/{name}.md:

- Conventions: Spec says Hamilton quaternions, code uses JPL (src/filters/ekf.ts:45)
- Parameters: Spec says Q=0.1, code has Q=0.01 (src/filters/ekf.ts:78)
- Structural: Function `predict()` in spec not found in code

Warnings:
- File src/filters/ekf.test.ts not found
```

### Step 6: Offer Resolution

Use `AskUserQuestion` to present options:

1. **Update spec to match code** — Code is correct, spec is outdated
2. **Update code to match spec** — Spec is correct, code drifted
3. **Review manually** — Need to investigate further

Execute the chosen option or provide guidance for manual review.

---

## Algorithm Doc Template

When creating new algorithm docs, use this template:

```markdown
---
owns:
- path/to/impl.py
- path/to/impl.cpp
---

# [Algorithm Name]

## Purpose

[What this solves. Where it fits in the system.]

## I/O

**Inputs:**
- `name` (type/shape): description [units/frame if applicable]

**Outputs:**
- `name` (type/shape): description [units/frame if applicable]

## Conventions

[Domain-specific conventions that affect correctness:
coordinate frames, rotation conventions, tensor layouts, sign conventions, etc.]

## Diagram

[Required. Visual representation of the algorithm flow.

Choose the style that best fits:
- Pipeline: A → B → C → D
- Architecture: Layered boxes
- Flowchart: Branches and decisions
- Data flow: Variable transformations
- Math flow: Equations connected by arrows]

## Method

[High-level description of the approach.]

### Step 1: [Name]

[Description with equations, variables, implementation hints as needed.]

### Step 2: [Name]

[Continue for each major step...]

---

## Implementation

[How spec maps to code:
- File structure and key functions
- Function → Step mapping
- Key constants and rationale]

## Notes

[Invariants, edge cases, validation approaches, known limitations.]
```

---

## Output Location

Algorithm specs: `agent-os/standards/algorithms/{name}.md`

After creating or updating specs, run `/index-standards` to update the index.

---

## Tips

- **Conventions section is critical** — This is where quaternion bugs, frame mismatches, and unit errors hide
- **Diagram is required** — Visual representation helps catch structural drift
- **owns: field enables drift detection** — Keep it updated when refactoring
- **Run periodically** — Drift accumulates silently over time
- **Check before releases** — Especially for safety-critical algorithms
100 changes: 100 additions & 0 deletions commands/agent-os/discover-standards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ If no area was specified:
- **Frontend areas:** UI components, styling/CSS, state management, forms, routing
- **Backend areas:** API routes, database/models, authentication, background jobs
- **Cross-cutting:** Error handling, validation, testing, naming conventions, file structure
- **Algorithms:** Filters, controllers, solvers, estimators, ML models, training loops, numerical methods, signal processing (use algorithm template — see "Discovering Algorithms" section below)
3. Use AskUserQuestion to present the areas:

```
Expand All @@ -30,6 +31,7 @@ I've identified these areas in your codebase:
2. **Database** (src/models/, src/db/) — Models, queries, migrations
3. **React Components** (src/components/) — UI patterns, props, state
4. **Authentication** (src/auth/) — Login, sessions, permissions
5. **Algorithms** (src/filters/, src/control/) — Filters, controllers, solvers

Which area should we focus on for discovering standards? (Pick one, or suggest a different area)
```
Expand Down Expand Up @@ -91,6 +93,7 @@ For each standard (after completing Step 3's Q&A):

1. Determine the appropriate folder (create if needed):
- `api/`, `database/`, `javascript/`, `css/`, `backend/`, `testing/`, `global/`
- `algorithms/` — For algorithmic/mathematical code (see "Discovering Algorithms" section)

2. Check if a related standard file already exists — append to it if so

Expand Down Expand Up @@ -158,6 +161,103 @@ Standards created for [area]:
Would you like to discover standards in another area, or are we done?
```

---

## Discovering Algorithms

When the user selects "Algorithms" as the focus area, use a different flow. Algorithm documentation requires more structure to prevent convention bugs in mathematical/computational code.

### Algorithm Step 1: Identify Algorithms

Scan for algorithmic patterns:
- Filters, estimators, state estimation
- Controllers, planners, optimizers, solvers
- ML models, training loops, loss functions
- Numerical methods, simulations
- Signal processing, transforms
- Kinematics, dynamics

Present findings:

```
I found these potential algorithms in your codebase:

1. **EKF** (src/filters/ekf.cpp, src/filters/ekf.h) — State estimation filter
2. **QP Solver** (src/control/qp_solver.py) — Quadratic programming optimization
3. **CNN Classifier** (src/models/classifier.py, src/models/layers.py) — Image classification

Which would you like to document?
```

### Algorithm Step 2: For Each Algorithm, Ask High-Level Questions

Follow the algorithm template structure. Ask about:

1. **Purpose**: "What does this algorithm do? What problem does it solve?"

2. **I/O**: "What are the inputs and outputs? What are their types, shapes, units?"

3. **Files (owns:)**: "Which files implement this algorithm? (I found: src/filters/ekf.cpp, src/filters/ekf.h — are there others?)"

4. **Conventions**: "Are there domain-specific conventions that affect correctness?"
- This is open-ended — don't assume. Could be:
- Coordinate frames (robotics)
- Quaternion conventions (robotics, graphics)
- Tensor layouts (ML)
- Units (scientific)
- Sign conventions (control systems)
- If user says none, that's fine

5. **Method**: "What are the key steps of this algorithm?"

### Algorithm Step 3: Create Algorithm File

Use the algorithm template (embedded in `/algorithm-drift` command):

```markdown
---
owns:
- src/filters/ekf.cpp
- src/filters/ekf.h
---

# Extended Kalman Filter

## Purpose
[From user's answer]

## I/O
**Inputs:**
- [From user's answer with types/units]

**Outputs:**
- [From user's answer with types/units]

## Conventions
[From user's answer, or "None identified" if not applicable]

## Diagram
[Generate based on method description]

## Method
[From user's answer, structured as steps]

## Implementation
- `ekf.cpp` — Main filter implementation
- `ekf.h` — State and covariance types

## Notes
[Any edge cases, invariants, or validation notes from discussion]
```

Create in `agent-os/standards/algorithms/{name}.md`

### Algorithm Step 4: Continue

Repeat for each selected algorithm, then update index as usual.

---

## Output Location

All standards: `agent-os/standards/[folder]/[standard].md`
Expand Down
Empty file added standards/algorithms/.gitkeep
View file
Open in desktop
Empty file.