|
| 1 | +# AI Assistant Specification |
1 | 2 |
|
2 | | -# AI Assistant Instructions |
| 3 | +## Machine-Readable Artefacts |
| 4 | + |
| 5 | +The `.machine_readable/` directory contains structured metadata required for automated reasoning and project introspection. |
| 6 | + |
| 7 | +- `STATE.scm`: Current project state, milestones, and progress. |
| 8 | +- `META.scm`: Architecture decisions, development methodology, and rationale. |
| 9 | +- `ECOSYSTEM.scm`: Ecosystem placement, upstream/downstream relationships, and interoperability. |
| 10 | +- `AGENTIC.scm`: AI agent interaction patterns, affordances, and constraints. |
| 11 | +- `NEUROSYM.scm`: Neurosymbolic integration configuration and hybrid reasoning settings. |
| 12 | +- `PLAYBOOK.scm`: Operational runbook, workflows, and incident procedures. |
3 | 13 |
|
4 | 14 | ## Repository Focus |
5 | | -- `rsr-template-repo` is treated as a Rhodium Standard Repository; obey the Rhodium policies, maintain `.bot_directives`, and keep `.machines_readable/6scm/` authoritative. |
| 15 | + |
| 16 | +- `fireflag` is treated as a Rhodium Standard Repository; obey the Rhodium policies, maintain `.bot_directives`, and keep `.machine_readable/` authoritative. |
6 | 17 | - Prefer to keep generated files out of source control, and regenerate them with the documented commands before committing. |
7 | 18 |
|
8 | 19 | ## Workflow |
9 | | -1. Inspect `.machines_readable/6scm/STATE.scm` for blockers and next actions. |
10 | | -2. Respect any constraints listed inside `.machines_readable/6scm/AGENTIC.scm` when tooling changes are requested. |
| 20 | + |
| 21 | +1. Inspect `.machine_readable/STATE.scm` for blockers and next actions. |
| 22 | +2. Respect any constraints listed inside `.machine_readable/AGENTIC.scm` when tooling changes are requested. |
11 | 23 | 3. After finishing edits, update STATE with your outcomes and commit with a concise, imperative message. |
12 | 24 |
|
13 | 25 | ## Delivery Promises |
| 26 | + |
14 | 27 | - Mention in summaries whether STATE, `contractiles/`, or `.bot_directives/` changed. |
15 | | -- Keep this file in sync with the repository’s status; update it if the governance changes. |
| 28 | +- Keep this file in sync with the repository's status; update it if the governance changes. |
| 29 | + |
| 30 | +## Repository Roots |
| 31 | + |
| 32 | +- Local repository root: `/var/mnt/eclipse/repos` |
| 33 | +- Remote mapping: `https://github.com/hyperpolymath/<name>` |
| 34 | +- Repository names are lowercase; dots (`.`) are replaced with hyphens (`-`). |
| 35 | +- If a repository is missing locally, check the remote and synchronize before proceeding. |
| 36 | + |
| 37 | +## AI CLI Standards |
| 38 | + |
| 39 | +- Include `ai-cli-crash-capture/` and `contractiles/` from this template in all new repositories. |
| 40 | +- Mirror all 6SCM files into `.machine_readable/`. |
| 41 | +- Before generating code, inspect `/var/mnt/eclipse/repos/proven` for the current Idris "unbreakable" library status. |
| 42 | +- If the project depends on the unbreakable Idris library, add an *Idris Inside* badge to the repository. |
| 43 | +- When new bindings are required, create them under `/var/mnt/eclipse/repos/proven` using the naming pattern `idris2-zig-<language>`. |
| 44 | +- If new code implies additional unbreakable Idris modules, add them to `/var/mnt/eclipse/repos/proven` and update binders across all supported languages. |
| 45 | + |
| 46 | +## Language Policy |
| 47 | + |
| 48 | +### Allowed Languages and Tools |
| 49 | + |
| 50 | +| Language/Tool | Use Case | Notes | |
| 51 | +|---------------|----------|-------| |
| 52 | +| ReScript | Application code | Type-safe, compiles to JS | |
| 53 | +| Deno | Runtime and package management | Replaces Node/npm/bun | |
| 54 | +| Rust | Systems, performance-critical, WASM | Preferred for CLI tools | |
| 55 | +| Tauri 2.0+ | Mobile apps (iOS/Android) | Rust backend + web UI | |
| 56 | +| Dioxus | Mobile apps (native UI) | Pure Rust, React-like | |
| 57 | +| Gleam | Backend services | BEAM or JS targets | |
| 58 | +| Bash/POSIX Shell | Automation scripts | Keep minimal | |
| 59 | +| JavaScript | Only where ReScript cannot | MCP glue, Deno APIs | |
| 60 | +| Nickel | Configuration | Complex config logic | |
| 61 | +| Guile Scheme | Metadata/state files | For all `.scm` artefacts | |
| 62 | +| Julia | Batch/data processing | Per RSR | |
| 63 | +| OCaml | AffineScript compiler | Language-specific | |
| 64 | +| Ada | Safety-critical systems | Where required | |
| 65 | + |
| 66 | +### Banned Languages and Tools |
| 67 | + |
| 68 | +| Banned | Replacement | |
| 69 | +|--------|-------------| |
| 70 | +| TypeScript | ReScript | |
| 71 | +| Node.js | Deno | |
| 72 | +| npm | Deno | |
| 73 | +| Bun | Deno | |
| 74 | +| pnpm/yarn | Deno | |
| 75 | +| Go | Rust | |
| 76 | +| Python | Julia / Rust / ReScript | |
| 77 | +| Java/Kotlin | Rust / Tauri / Dioxus | |
| 78 | +| Swift | Tauri / Dioxus | |
| 79 | +| React Native | Tauri / Dioxus | |
| 80 | +| Flutter/Dart | Tauri / Dioxus | |
| 81 | + |
| 82 | +## Mobile Development Policy |
| 83 | + |
| 84 | +A strict Rust-first approach applies. |
| 85 | + |
| 86 | +- Use **Tauri 2.0+** for web UI (ReScript) + Rust backend. |
| 87 | +- Use **Dioxus** for pure Rust native UI. |
| 88 | + |
| 89 | +Both are FOSS with independent governance. |
| 90 | + |
| 91 | +## Enforcement Rules |
| 92 | + |
| 93 | +- Do not create new TypeScript files; convert existing TS to ReScript. |
| 94 | +- Do not use `package.json` for runtime dependencies; use `deno.json` imports. |
| 95 | +- Do not include `node_modules` in production; Deno handles dependency caching. |
| 96 | +- Do not use Go; use Rust. |
| 97 | +- Do not use Python; use Julia (data/batch), Rust (systems), or ReScript (apps). |
| 98 | +- Do not use Kotlin/Swift; use Tauri 2.0+ or Dioxus for mobile. |
| 99 | + |
| 100 | +## Package Management |
| 101 | + |
| 102 | +- Primary: Guix (`guix.scm`) |
| 103 | +- Fallback: Nix (`flake.nix`) |
| 104 | +- JavaScript dependencies: Deno (`deno.json` imports) |
| 105 | + |
| 106 | +## Security Requirements |
| 107 | + |
| 108 | +- Do not use MD5 or SHA-1; use SHA-256 or stronger. |
| 109 | +- Use HTTPS only. |
| 110 | +- Do not hardcode secrets. |
| 111 | +- Pin all dependencies by SHA. |
| 112 | +- Include SPDX license headers in all files. |
0 commit comments