Skip to content

Commit 6c899df

Browse files
fazxesfazxes
authored
Merge pull request #77 from Recusive/feat/migration-granular
feat: Orbit v0.0.7 codebase (granular commits)
2 parents c0e8b96 + 787d5b9 commit 6c899df

3,227 files changed

Lines changed: 313287 additions & 5023 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/commands/audit-spec.md‎

Lines changed: 428 additions & 0 deletions
Large diffs are not rendered by default.

‎.claude/commands/changelog.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
---
2+
description: Generate a marketing-quality changelog for a release version
3+
argument-hint: <version> [pr-number]
4+
allowed-tools: Bash(gh:*), Bash(git diff:*), Bash(git log:*), Bash(git branch:*), Bash(git status:*), Read, Write, Edit, Glob, Grep
5+
---
6+
7+
# Changelog Generator
8+
9+
Generate a changelog for Orbit release `$1`, written for the marketing site. If a PR number `$2` is provided, pull its metadata from GitHub.
10+
11+
## Validation
12+
13+
If `$1` is empty, output:
14+
15+
```
16+
Usage: /changelog <version> [pr-number]
17+
Examples:
18+
/changelog v0.0.7
19+
/changelog v0.0.7 74
20+
```
21+
22+
Stop execution.
23+
24+
## Step 0: Resolve Version
25+
26+
The version is `$1`. Determine whether it's a version or a PR number:
27+
28+
- **Pure integer** (e.g., `73`, `104`) → This is a PR number, not a version. Infer the version from the current branch name and use `$1` as the PR number.
29+
- **Contains dots** (e.g., `0.0.7`, `v0.0.7`) → This is a version. Prepend `v` if missing.
30+
- **Starts with `v`** (e.g., `v0.0.7`) → This is a version. Use as-is.
31+
32+
To get the branch name for fallback:
33+
34+
```bash
35+
git branch --show-current
36+
```
37+
38+
---
39+
40+
## Step 1: Gather Context
41+
42+
Collect all raw material. Run these commands:
43+
44+
```bash
45+
git branch --show-current
46+
git log main..HEAD --oneline
47+
git diff main --stat
48+
git diff main --name-only
49+
git status --short
50+
```
51+
52+
If a PR number is available (either `$2`, or `$1` if it was a bare number):
53+
54+
```bash
55+
gh pr view <pr-number> --json title,body,commits,files
56+
```
57+
58+
Check if a changelog already exists by reading `docs/changelog-<version>.md`. If it exists, you are **updating** — preserve existing content and add new entries. Do not rewrite what's already there.
59+
60+
If the existing changelog already covers all committed and uncommitted changes, print `Changelog is up to date — nothing new to add.` and stop.
61+
62+
Read `docs/changelog-v0.0.6.md` as the **tone and structure reference**. Match its style exactly.
63+
64+
---
65+
66+
## Step 2: Categorize Changes
67+
68+
Group everything into user-facing categories. Use your judgment — not every commit deserves a section.
69+
70+
| Category | What goes here |
71+
| ---------------- | ------------------------------------------------------------------------- |
72+
| **New features** | Genuinely new capabilities a user would notice |
73+
| **Improvements** | Meaningful enhancements to existing features |
74+
| **Bug fixes** | Things that were broken and are now fixed |
75+
| **In-progress** | Uncommitted or WIP work that's substantial enough to mention |
76+
| **Internal** | Only if genuinely interesting (new infra, major cleanup). Skip if boring. |
77+
78+
**Discard:**
79+
80+
- Routine refactors that don't change behavior
81+
- File renames, import reordering, lint fixes
82+
- Test additions (unless they represent a new testing capability)
83+
- Documentation changes (unless they're user-facing docs)
84+
85+
---
86+
87+
## Step 3: Write the Changelog
88+
89+
Create or update `docs/changelog-<version>.md`.
90+
91+
### Format
92+
93+
```markdown
94+
# Orbit <version>
95+
96+
_<Month Year>_
97+
98+
---
99+
100+
## <Category Name>
101+
102+
### <Feature or improvement name>
103+
104+
<1-2 paragraphs describing what the user gets. Not what files changed.>
105+
106+
---
107+
108+
## Bug Fixes
109+
110+
- **<Short name>** — <What was broken, now fixed.>
111+
112+
---
113+
114+
## <Feature Name> _(in progress)_
115+
116+
<One paragraph. What it will do. Note it ships in a later release.>
117+
118+
---
119+
120+
## Internal
121+
122+
- <One-liner only>
123+
```
124+
125+
### Writing Rules
126+
127+
These are non-negotiable:
128+
129+
1. **Lead with what users get.** "The branch picker now always shows search and branch creation" — not "Removed conditional Select/Popover logic."
130+
131+
2. **No internal naming.** Never mention token names (`orbit-100`, `surface-primary`), store names (`useGitStore`), CSS variable names (`--color-border-subtle`), file paths, or function names.
132+
133+
3. **No design system implementation details** unless the design system itself is the feature. "Consistent colors across light and dark themes" is fine. "Migrated from Radix 12-step scales to a 10-step primitive scale with three semantic layers" is not.
134+
135+
4. **Don't elevate routine cleanup.** Removing dead code, fixing lint, updating dependencies — these are not features. If they're significant enough (e.g., 900+ lines of dead CSS removed), fold them into the relevant section as a supporting detail, not a headline.
136+
137+
5. **Bug fixes are one-liners.** State what broke and that it's fixed. Don't explain the implementation.
138+
139+
6. **In-progress features get one paragraph.** What it will do, what's built so far at a high level, and that it ships later.
140+
141+
7. **Internal section uses one-liners.** If there's nothing interesting, omit the section entirely.
142+
143+
8. **Don't sound impressed by your own work.** No "comprehensive", "robust", "elegant", "powerful". Just say what it does.
144+
145+
9. **Match the reference.** Read `docs/changelog-v0.0.6.md` before writing. Your output should feel like the same person wrote both.
146+
147+
---
148+
149+
## Step 4: Output
150+
151+
After writing the file:
152+
153+
1. Print: `Changelog written to docs/changelog-<version>.md`
154+
2. Print the full changelog content
155+
3. If updating an existing file, note what was added

‎.claude/commands/implement.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
---
2+
description: Implement a feature from an approved plan and spec sheet, phase by phase with AC verification
3+
argument-hint: <path-to-plan> <path-to-spec>
4+
allowed-tools: Read, Edit, Write, Glob, Grep, Bash, Agent, AskUserQuestion, LSP
5+
---
6+
7+
# Feature Implementation
8+
9+
You are a senior implementation engineer working in a production TypeScript/React/Rust/Tauri monorepo. You implement exactly what was planned and specified — no shortcuts, no gold-plating, no improvisation.
10+
11+
<inputs>
12+
<plan_path>$1</plan_path>
13+
<spec_path>$2</spec_path>
14+
</inputs>
15+
16+
If either path is empty, output the usage and stop:
17+
18+
```
19+
Usage: /implement <path-to-plan> <path-to-spec>
20+
```
21+
22+
---
23+
24+
## Principles
25+
26+
These govern every decision. When in doubt, return here.
27+
28+
1. **Spec = WHAT.** Behavior, ACs, data contracts, error messages. If the spec doesn't address it, ask the user.
29+
2. **Plan = HOW.** Files, phases, architecture. Follow its structure.
30+
3. **Codebase wins conflicts.** When plan examples contradict actual codebase conventions, match the codebase.
31+
4. **ACs are contracts.** Never claim an AC passes without running the verification command.
32+
5. **No gold-plating.** If it's not in the plan or spec, don't build it.
33+
6. **Ask before guessing** on ambiguities that affect architecture or behavior.
34+
35+
---
36+
37+
## AC Status Definitions
38+
39+
Use these consistently in phase reports and the final report:
40+
41+
- **PASS**: Verified by running a command or test
42+
- **PENDING [Phase N]**: Cannot verify yet — depends on a later phase
43+
- **MANUAL**: Requires hardware, UI interaction, or manual testing
44+
- **PARTIAL**: Implemented but needs manual verification (explain what to check)
45+
- **BLOCKED**: Cannot verify without unavailable infrastructure (explain what's needed)
46+
- **MISSING**: Not implemented (explain why)
47+
48+
---
49+
50+
## Preparation (silent — do not output analysis or status)
51+
52+
Read all of these before writing any code:
53+
54+
1. **Plan** — extract phases, files, architecture, inter-phase dependencies
55+
2. **Spec** — extract ACs with priorities, data contracts, error taxonomy, constraints
56+
3. **Relevant CLAUDE.md files** — root + sub-level for every area you'll touch
57+
4. **Every existing file** the plan references — note actual signatures, types, patterns
58+
5. **Neighboring files** for every new file — learn local conventions, check barrel exports
59+
60+
Then map which ACs become satisfiable after which plan phase.
61+
62+
---
63+
64+
## Execution
65+
66+
### 1. Output the implementation sequence, then immediately start
67+
68+
Do NOT wait for user confirmation. Output this once, then begin Phase 1:
69+
70+
```
71+
## Implementation Sequence
72+
73+
**Feature**: [name]
74+
**Phases**: [N] | **ACs**: [total] (P0: n, P1: n, P2: n, P3: n)
75+
76+
Phase 1: [name] → [files] → ACs: [list]
77+
Phase 2: [name] → [files] → ACs: [list]
78+
...
79+
```
80+
81+
### 2. Execute every plan phase continuously
82+
83+
Work through every plan phase in order. Do NOT stop between phases to ask permission — just proceed. Only stop for genuine blockers you cannot resolve (spec ambiguity, missing section, compile error after two fix attempts).
84+
85+
**For each plan phase:**
86+
87+
**Announce:**
88+
89+
```
90+
## Phase [N]: [Name]
91+
[files being created/modified] | ACs: [targeted]
92+
```
93+
94+
**Before implementing**, identify which types, functions, or files from previous phases this phase depends on.
95+
96+
**Implement** following all code quality rules from CLAUDE.md. Additionally:
97+
98+
- New files: read a neighbor first for conventions; add to barrel exports (index.ts / mod.rs)
99+
- Modified files: re-read first (may have changed from earlier phases); make minimum changes
100+
- Use exact error message templates from the spec's Error Taxonomy
101+
- Match the spec's data contract types exactly
102+
103+
**Validate:**
104+
105+
1. Run `bun run typecheck` (if TypeScript changed) and/or `cargo check` (if Rust changed) — fix errors before continuing
106+
2. Run `bun run lint` if you created new files or made structural changes
107+
3. For each targeted AC: run the verification command if one exists. Never claim PASS from reading code alone when a command could verify it.
108+
109+
**Report** (3-5 lines, then continue to next phase):
110+
111+
<example>
112+
Phase 2 complete. Created: `src/hooks/browser/use-browser-nav.ts`. Modified: `src/hooks/browser/index.ts`, `src/stores/browser/browser-store.ts`.
113+
AC-4 (P0): PASS — `bun run typecheck` clean, hook returns `BrowserNavState`. AC-5 (P1): PASS — store triggers re-render (verified via test). AC-7 (P1): PENDING [Phase 4] — needs toolbar integration.
114+
Plan drift: Plan referenced `useBrowserStore.getState().activeTab` but store uses `.tabs.active`. Adapted to match codebase.
115+
</example>
116+
117+
---
118+
119+
## Final Validation
120+
121+
After all plan phases complete:
122+
123+
1. **Run full quality gates** — fix any failures:
124+
125+
```
126+
bun run check # typecheck + lint + tests
127+
cargo clippy # if Rust touched
128+
cargo test # if Rust touched
129+
```
130+
131+
2. **AC sweep** — walk every AC in the spec and assign a status (see AC Status Definitions above).
132+
133+
3. **Output final report:**
134+
135+
```
136+
## Implementation Complete
137+
138+
**Feature**: [name] | **Branch**: [branch] | **Date**: [date]
139+
140+
### Files Changed
141+
142+
| File | Action | Phase |
143+
|------|--------|-------|
144+
| `path` | Created/Modified | Phase N |
145+
146+
### Acceptance Criteria
147+
148+
| AC | Pri | Status | Verification |
149+
|----|-----|--------|--------------|
150+
| AC-1 | P0 | PASS | `bun run typecheck` clean + test passes |
151+
152+
**Summary**: [N]/[total] ACs satisfied. All P0s passing.
153+
154+
### Quality Gates
155+
156+
| Check | Status |
157+
|-------|--------|
158+
| TypeScript (`bun run typecheck`) | PASS/FAIL |
159+
| ESLint (`bun run lint`) | PASS/FAIL |
160+
| Frontend tests (`bun run test`) | PASS/FAIL |
161+
| Clippy (`cargo clippy`) | PASS/FAIL or N/A |
162+
| Rust tests (`cargo test`) | PASS/FAIL or N/A |
163+
164+
### Issues & Deferred Items
165+
166+
[Plan drift, skipped P3 items, observations worth noting]
167+
168+
### Next Steps
169+
170+
1. [e.g., manual verification for AC-12, AC-15]
171+
2. [e.g., run /audit-spec to verify spec accuracy]
172+
3. [e.g., create PR targeting main]
173+
```
174+
175+
---
176+
177+
## Error Recovery
178+
179+
- **Compile errors**: Check actual codebase types, not what the plan assumed. Fix simply. Note drift in phase report.
180+
- **Plan drift**: File, function, or API doesn't exist where plan says? Search for the real location, adapt, note it.
181+
- **Ambiguity**: Check spec's Open Questions → neighboring code patterns → ask the user.
182+
- **Missing spec sections**: Flag the gap to the user. Do not fill it yourself.
183+
- **Scope creep**: Do not implement it. Note under "Observations" for the user to decide.
184+
- **Broken existing tests**: Fix them. Do not delete unless the plan explicitly says to.
185+
186+
---
187+
188+
Begin by reading the plan and spec documents.

0 commit comments

Comments
 (0)