Skip to content

Commit 2b95d5c

Browse files
Add MCP servers and project skills for Athas development
Add project-level MCP configuration and skills to streamline development: MCP Servers (.factory/mcp.json): - GitHub: Full API access for repos, issues, PRs, actions - Sequential Thinking: Structured step-by-step reasoning for debugging - Playwright: Browser testing and automation - Sentry: Error tracking and monitoring - Linear: Issue tracking and project management Skills (.factory/skills/): - athas-bug-fix: Standardized bug diagnosis and fix workflow - athas-performance: Performance bottleneck identification and optimization - athas-release: Release process following project conventions - athas-contribution: Contribution standards and commit conventions Co-authored-by: factory-droid[bot] <138933559+factory-droid[bot]@users.noreply.github.com>
1 parent e871e77 commit 2b95d5c

5 files changed

Lines changed: 342 additions & 0 deletions

File tree

.factory/mcp.json

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
{
2+
"mcpServers": {
3+
"github": {
4+
"type": "http",
5+
"url": "https://api.githubcopilot.com/mcp/",
6+
"disabled": false
7+
},
8+
"sequential-thinking": {
9+
"type": "stdio",
10+
"command": "npx",
11+
"args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
12+
"disabled": false
13+
},
14+
"playwright": {
15+
"type": "stdio",
16+
"command": "npx",
17+
"args": ["-y", "@playwright/mcp@latest"],
18+
"disabled": false
19+
},
20+
"sentry": {
21+
"type": "http",
22+
"url": "https://mcp.sentry.dev/mcp",
23+
"disabled": false
24+
},
25+
"linear": {
26+
"type": "http",
27+
"url": "https://mcp.linear.app/mcp",
28+
"disabled": false
29+
}
30+
}
31+
}
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: athas-bug-fix
3+
description: Standardized workflow for diagnosing and fixing bugs in the Athas codebase. Use when the user mentions "bug", "fix", "issue", or references a GitHub issue number.
4+
---
5+
6+
# Athas Bug Fix Workflow
7+
8+
## Context
9+
10+
Athas is a lightweight, cross-platform code editor built with Tauri (Rust backend + React/TypeScript frontend). The codebase has two distinct layers:
11+
12+
- **Frontend** (`src/`): TypeScript/React using Zustand stores, Tauri plugin APIs, xterm.js
13+
- **Backend** (`src-tauri/`, `crates/`): Rust with Tauri commands, tokio async runtime
14+
15+
## Instructions
16+
17+
### 1. Understand the Bug
18+
19+
- If a GitHub issue number is given, read the issue for reproduction steps and environment details
20+
- Identify which layer is affected: frontend (TypeScript), backend (Rust), or both
21+
- Check the issue labels for hints: `Linux`, `macOS`, `Native`, `Git`, `Workspaces`, etc.
22+
23+
### 2. Locate Relevant Code
24+
25+
- **Frontend bugs**: Search in `src/features/<feature>/` — each feature has its own directory with stores, components, and hooks
26+
- **Backend bugs**: Search in `crates/<crate>/src/` for the relevant Rust crate, or `src-tauri/src/commands/` for Tauri command handlers
27+
- Use `git log --oneline -- <path>` to see recent changes that may have introduced the bug
28+
- Check `git log --all --oneline --grep="<keyword>"` for prior fixes in the same area
29+
30+
### 3. Trace the Root Cause
31+
32+
- Follow the data flow from the user action to the bug symptom
33+
- For frontend bugs: trace from component → hook → store → Tauri invoke
34+
- For backend bugs: trace from Tauri command → crate function → system call
35+
- Look for race conditions (especially `void (async () => { ... })()` patterns), stale state, and missing cleanup
36+
- Check if the bug was introduced by a recent commit (use `git bisect` if needed)
37+
38+
### 4. Implement the Fix
39+
40+
- Match the existing code style: immer middleware for Zustand stores, Tauri command patterns in Rust
41+
- Preserve existing error handling patterns
42+
- Add comments explaining non-obvious fixes, referencing the issue number (e.g., `// Fix #581: ...`)
43+
- Do NOT add logging or debug statements unless the existing code already uses it
44+
45+
### 5. Verify
46+
47+
Run these checks before considering the fix complete:
48+
49+
```bash
50+
# TypeScript type check (must pass)
51+
bun run typecheck
52+
53+
# Lint changed files
54+
npx oxlint <changed-files>
55+
56+
# Rust format check (for Rust changes)
57+
cargo rustfmt --check <changed-rust-files>
58+
```
59+
60+
**Important**: Full `cargo check` requires glib >= 2.70 (Ubuntu 22.04+). If on an older system, verify Rust syntax manually and rely on CI for compilation.
61+
62+
### 6. Cross-Verify
63+
64+
Before finalizing, verify:
65+
- No removed imports are still used by other code
66+
- No callers of changed functions are broken
67+
- The fix doesn't introduce new race conditions
68+
- Terminal PTY lifecycle is respected (cleanup happens via React useEffect, not synchronously)
69+
70+
## Key Codebase Conventions
71+
72+
- State management: Zustand with immer middleware (`createWithEqualityFn`, `createSelectors`)
73+
- Async patterns: Background init uses `void (async () => { ... })()` — be careful of race conditions
74+
- Session persistence: `useSessionStore` with zustand/persist, terminal sessions in localStorage
75+
- GitHub CLI: Uses `gh` binary via `resolve_gh_binary()` with user shell PATH resolution
76+
- Performance: Avoid per-entry I/O in loops (stat syscalls, Tauri IPC); prefer lazy resolution
Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
name: athas-contribution
3+
description: Ensure contributions follow the Athas project conventions. Use when the user mentions "contribute", "PR", "commit", or "pull request".
4+
---
5+
6+
# Athas Contribution Workflow
7+
8+
## Context
9+
10+
Athas enforces contribution standards via:
11+
- **commitlint**: Conventional commit format enforced by pre-commit hooks
12+
- **AGENTS.md**: Project-specific rules and conventions for AI agents
13+
- **oxlint/oxfmt**: Linting and formatting (via vite-plus / vp check)
14+
- **TypeScript strict mode**: `tsc --noEmit` must pass with zero errors
15+
16+
## Instructions
17+
18+
### 1. Pre-Commit Checks
19+
20+
Before committing, ensure:
21+
22+
```bash
23+
# TypeScript type check (MUST pass)
24+
bun run typecheck
25+
26+
# Lint and auto-fix
27+
bun run fix
28+
29+
# Format check
30+
bun run format
31+
```
32+
33+
If the full `bun check` fails due to Node.js version incompatibility (requires Node >= 22), run individual checks instead:
34+
35+
```bash
36+
npx oxlint <changed-files>
37+
bun run typecheck
38+
cargo rustfmt --check <changed-rust-files>
39+
```
40+
41+
### 2. Commit Message Format
42+
43+
Follow the **conventional commit** format enforced by commitlint:
44+
45+
```
46+
<type>(<scope>): <subject>
47+
48+
<body>
49+
50+
Co-authored-by: ...
51+
```
52+
53+
**Types**: `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `perf`, `test`, `ci`
54+
55+
**Examples**:
56+
- `fix: Resolve gh CLI auth detection on expired tokens`
57+
- `feat(git): Add workspace state persistence across folder switches`
58+
- `perf: Remove per-entry symlink resolution from directory listing`
59+
- `chore: Bump version to 0.4.5-alpha.9`
60+
61+
### 3. PR Conventions
62+
63+
- **One logical change per commit** — squash related tweaks into a single commit
64+
- **Rebase on master** before submitting: `git rebase origin/master`
65+
- **Title**: Imperative mood, concise (e.g., "Fix workspace switch race condition")
66+
- **Body**: Reference issue numbers, explain the "why" not the "what"
67+
- Include `Co-authored-by:` for AI-assisted commits
68+
69+
### 4. AGENTS.md Rules
70+
71+
Key rules from the project's AGENTS.md:
72+
- PR descriptions must follow the project format
73+
- JSDoc comments on utility functions
74+
- Don't add unnecessary comments — code should be self-documenting
75+
- Follow existing code style in the surrounding context
76+
77+
### 5. Code Review Checklist
78+
79+
Before marking a PR ready:
80+
- [ ] `tsc --noEmit` passes with zero errors
81+
- [ ] `oxlint` passes on changed files
82+
- [ ] No sensitive data (tokens, keys, passwords) in the diff
83+
- [ ] Commit messages follow conventional format
84+
- [ ] Changes are logically grouped (one concern per commit)
85+
- [ ] No regressions: removed imports not used elsewhere, changed signatures not breaking callers
Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
name: athas-performance
3+
description: Workflow for identifying and fixing performance bottlenecks in the Athas editor. Use when the user mentions "lag", "slow", "performance", "benchmark", "optimize", or "CachyOS".
4+
---
5+
6+
# Athas Performance Optimization Workflow
7+
8+
## Context
9+
10+
Athas is a Tauri-based editor (Rust + React). Common performance bottlenecks:
11+
12+
1. **File I/O overhead**: Per-entry stat syscalls, double file reads, large file loading
13+
2. **Tree-sitter parsing**: WASM initialization cost, grammar compilation
14+
3. **WebView rendering**: GPU compositing on Linux (webkit2gtk), DOM updates
15+
4. **Tauri IPC overhead**: Each `invoke()` call has serialization/deserialization cost
16+
17+
## Instructions
18+
19+
### 1. Identify the Bottleneck
20+
21+
- Use `fileOpenBenchmark` marks in console to trace file-open timing
22+
- Use `frontendTrace` events to see workspace-open phase durations
23+
- Check if the issue is on first-open or subsequent interactions
24+
- Determine if it's I/O-bound (file reading, directory listing) or CPU-bound (parsing, rendering)
25+
26+
### 2. Profile the Hot Path
27+
28+
For **file opening** latency:
29+
- Check `readDirectoryContents()` — does it call `getSymlinkInfo()` per entry?
30+
- Check `handleFileSelect()` — is the file read twice (binary sniff + content read)?
31+
- Check `readFileContent()` vs `readFile()` from `@tauri-apps/plugin-fs`
32+
33+
For **directory listing** latency:
34+
- Each `invoke("get_symlink_info")` is a stat syscall + IPC round-trip
35+
- `Promise.all()` masks individual latency but not total wall time
36+
- Large directories (1000+ entries) multiply per-entry costs
37+
38+
For **rendering** latency:
39+
- Check if DMABUF renderer is disabled on Linux (`WEBKIT_DISABLE_DMABUF_RENDERER=1`)
40+
- Look for unnecessary re-renders in React components (missing memoization)
41+
- Check if virtualized lists are used for large collections
42+
43+
### 3. Implement the Optimization
44+
45+
Common patterns:
46+
47+
- **Lazy resolution**: Defer expensive operations (like symlink resolution) to when data is actually needed, not during batch reads
48+
- **Single-pass I/O**: Read files once, decode in-memory. Use `TextDecoder` on `Uint8Array` instead of reading twice
49+
- **Batched IPC**: Minimize Tauri `invoke()` calls in loops; prefer single calls that return bulk data
50+
- **Virtualization**: Use `@tanstack/react-virtual` for large lists (already used for file tree and editor)
51+
- **Debounced saves**: Workspace session saves are already debounced via `workspace-session-save-queue.ts`
52+
53+
### 4. Verify the Improvement
54+
55+
```bash
56+
# TypeScript type check
57+
bun run typecheck
58+
59+
# Lint
60+
npx oxlint <changed-files>
61+
```
62+
63+
Compare benchmark marks before and after. Target:
64+
- Directory listing: < 100ms for typical projects (was 30-40s with per-entry stat)
65+
- File opening: < 250ms for typical files (warn threshold in benchmarks)
66+
- Tab switching: instant (no re-read needed for already-opened buffers)
67+
68+
## Key Performance Files
69+
70+
- `src/features/editor/utils/file-open-benchmark.ts` — Timing instrumentation
71+
- `src/utils/frontend-trace.ts` — Structured tracing
72+
- `src/features/file-system/controllers/file-operations.ts` — Directory reading
73+
- `src/features/file-system/controllers/store.ts` — File opening path
74+
- `src-tauri/src/main.rs` — Linux DMABUF renderer disable
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: athas-release
3+
description: Guide the release process following Athas's established conventions. Use when the user mentions "release", "publish", "version bump", or "tag".
4+
disable-model-invocation: true
5+
---
6+
7+
# Athas Release Workflow
8+
9+
## Context
10+
11+
Athas uses a structured release process with:
12+
- **Version scheme**: Semver with alpha/beta/rc suffixes (e.g., `0.4.5-alpha.8`)
13+
- **Package manager**: Bun for JS, Cargo for Rust
14+
- **CI**: GitHub Actions for building cross-platform releases (Linux, macOS, Windows)
15+
- **Commitlint**: Enforces conventional commit messages
16+
17+
## Instructions
18+
19+
### 1. Pre-Release Check
20+
21+
Run the validation script to ensure everything is ready:
22+
23+
```bash
24+
bun release:check
25+
```
26+
27+
This validates version consistency, changelog state, and build readiness.
28+
29+
### 2. Choose the Release Type
30+
31+
| Type | Command | Version Effect |
32+
|------|---------|---------------|
33+
| Patch | `bun release:patch` | 0.4.4 → 0.4.5 |
34+
| Minor | `bun release:minor` | 0.4.4 → 0.5.0 |
35+
| Major | `bun release:major` | 0.4.4 → 1.0.0 |
36+
| Alpha | `bun release:alpha` | 0.4.4 → 0.4.5-alpha.1 |
37+
| Beta | `bun release:beta` | 0.4.5-alpha.8 → 0.4.5-beta.1 |
38+
| RC | `bun release:rc` | 0.4.5-beta.1 → 0.4.5-rc.1 |
39+
40+
### 3. Run the Release
41+
42+
```bash
43+
# For a patch release
44+
bun release:patch
45+
46+
# For an alpha pre-release
47+
bun release:alpha
48+
```
49+
50+
The release script (`scripts/release.ts`) will:
51+
1. Bump the version in `package.json` and `src-tauri/tauri.conf.json`
52+
2. Update `Cargo.lock` if needed
53+
3. Create a git tag
54+
4. Push the tag to trigger the CI release workflow
55+
56+
### 4. Verify the CI Build
57+
58+
Check the GitHub Actions workflow:
59+
- Linux: `.deb`, `.rpm`, `.AppImage` builds
60+
- macOS: `.dmg` (aarch64)
61+
- Windows: `.exe` (arm64, x64)
62+
63+
If the build fails, fix the issue and re-tag.
64+
65+
### 5. Post-Release
66+
67+
- Verify the release appears on https://github.com/athasdev/athas/releases
68+
- Check that all expected assets are attached
69+
- Announce in Discord if it's a stable release
70+
71+
## Important Constraints
72+
73+
- NEVER push directly to `master` without going through the release script
74+
- Alpha/beta releases are marked as prerelease on GitHub
75+
- The Windows MSI versioning has special handling (see `scripts/` directory)
76+
- Commit messages must pass commitlint: use conventional format like `feat:`, `fix:`, `chore:`

0 commit comments

Comments
 (0)