web-abin/OpenGeno / skills/geno-init
geno-init
UnverifiedInitialize an OpenGeno feature tree for a project. Asks the user to pick a documentation language (English or Chinese, default English), a drift mode, and a generation mode (stub-only by default, or one-shot full docs that fills every L3 section now). Scans the codebase, proposes a module breakdown, generates the L1 root index, L2 module indexes and L3 feature docs in the chosen language, writes .feat-tree.json, and injects the OpenGeno workflow rules into CLAUDE.md (and AGENTS.md if present). Use when starting OpenGeno on a new project. Run once per project.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.6 KB |
| reference.md | markdown | 10.1 KB |
| scripts/drift-check.shexecutable | script | 2.8 KB |
| scripts/post-edit-warn.shexecutable | script | 1.9 KB |
| scripts/stop-check.shexecutable | script | 2.8 KB |
| templates/claude-md-injection.md | markdown | 3.7 KB |
| templates/claude-md-injection.zh.md | markdown | 3.6 KB |
| templates/feat-tree.json | config | 93 B |
| templates/feature-logic.md | markdown | 1.2 KB |
| templates/feature-logic.zh.md | markdown | 1.1 KB |
| templates/feature-ui.md | markdown | 2.1 KB |
| templates/feature-ui.zh.md | markdown | 2.0 KB |
| templates/module-index.md | markdown | 1.1 KB |
| templates/module-index.zh.md | markdown | 1011 B |
| templates/root-index.md | markdown | 1.4 KB |
| templates/root-index.zh.md | markdown | 1.3 KB |
reference.md
View on GitHub# OpenGeno / FeatTree — Doc Format Reference
This is the canonical specification of the feature tree document format. Every
skill in this library reads/writes documents according to this schema.
## Directory layout (in the host project)
```
<project-root>/
├── feat-tree/ # Default location, configurable via .feat-tree.json
│ ├── index.md # L1 root index — list of modules
│ ├── auth/
│ │ ├── index.md # L2 module index
│ │ ├── login.md # L3 feature doc
│ │ ├── signup.md
│ │ └── password-reset/ # Sub-module if a feature has multiple sub-features
│ │ ├── index.md
│ │ ├── request.md
│ │ └── confirm.md
│ ├── profile/
│ │ ├── index.md
│ │ └── ...
│ └── ...
└── .feat-tree.json # Optional config (paths, drift mode, etc.)
```
Three tiers, each with a fixed schema:
| Tier | File | Purpose | Read by AI |
|------|------|---------|------------|
| L1 | `feat-tree/index.md` | Project module list, ~500 tokens | Always (mounted in CLAUDE.md) |
| L2 | `feat-tree/<module>/index.md` | Sub-feature list of a module | When task touches that module |
| L3 | `feat-tree/<module>/<feature>.md` | Detailed feature spec | When task touches that feature |
## L1 — Root Index
```markdown
---
type: og-root
schema: 1
last_synced_commit: <git-sha-or-empty>
---
# <Project> Feature Tree
Generated by OpenGeno. AI agents must read this index first to locate the
relevant feature documentation before changing user-visible behavior.
## Modules
| Module | Description | Path |
|--------|-------------|------|
| Auth | Login, signup, session, password reset | [auth/](auth/index.md) |
| Profile | View/edit user profile | [profile/](profile/index.md) |
| ... | ... | ... |
## Out of scope
The following are NOT documented in this tree (they're cross-cutting
infrastructure, not user-observable features):
- i18n / translations
- Analytics / telemetry
- Build tooling, CI/CD
- Error reporting (Sentry, etc.)
- Logging
- Pure utility helpers
```
## L2 — Module Index
```markdown
---
type: og-module
module: auth
schema: 1
last_synced_commit: <git-sha-or-empty>
---
# Auth
One-paragraph overview of what this module covers and what it does NOT cover.
## Features
| Feature | Kind | Path |
|---------|------|------|
| Login | UI | [login.md](login.md) |
| Signup | UI | [signup.md](signup.md) |
| Password Reset | UI (multi-screen) | [password-reset/](password-reset/index.md) |
| Session Refresh | Logic | [session-refresh.md](session-refresh.md) |
## Cross-module dependencies
- `Profile` reads the user object that `Login` writes to `AuthState`.
- `Notifications` triggers password-reset flow on email link click.
```
## L3 — Feature Doc (UI)
```markdown
---
type: og-feature
kind: ui
feature: login
module: auth
schema: 1
code:
- lib/features/auth/login_page.dart
- lib/features/auth/login_controller.dart
- lib/api/auth_service.dart
last_synced_commit: <git-sha>
last_reviewed: 2026-05-06
---
# Login
One-paragraph summary of what this feature is and why it exists.
## Wireframe
```
┌────────────────────────────┐
│ ← back │
│ │
│ [logo] │
│ Sign in to <App> │
│ │
│ ┌──────────────────┐ │
│ │ email │ │
│ └──────────────────┘ │
│ ┌──────────────────┐ │
│ │ password │ │
│ └──────────────────┘ │
│ [ ] remember me │
│ │
│ [ Sign in ] │
│ │
│ forgot password? │
└────────────────────────────┘
```
ASCII or mermaid. Mermaid `flowchart` is preferred for state/flow diagrams.
## Entry points
How does the user arrive at this screen?
- Tap "Sign in" on landing page
- Deep link: `app://auth/login?redirect=...`
- Auto-redirect from any auth-required page
## Layout
Describe the structural composition. List sections top-to-bottom.
## Interactions
Numbered list of every interactive element with:
- Trigger (tap, type, swipe, etc.)
- Validation rules
- Visible feedback
- Resulting state change or navigation
## Logic
Business rules that aren't visible in the UI:
- API calls made (with paths and payload shape at high level)
- Storage writes (what gets persisted, how long)
- Side effects (events emitted, other modules notified)
## State
| State | Trigger | UI effect |
|-------|---------|-----------|
| idle | initial | empty form, button disabled |
| validating | typing | inline error if invalid |
| submitting | tap submit | spinner, fields disabled |
| error | API 401 | error toast, fields re-enabled |
| success | API 200 | navigate to redirect target |
## Animation
- Sign in button: scale 1.0 → 0.95 on press, 100ms
- Error toast: slide-down 200ms ease-out
- Page transition: standard platform push
## Cross-feature links
- → [Password Reset](password-reset/index.md) (forgot password link)
- → [Session Refresh](session-refresh.md) (after successful login)
- ← [Landing](../onboarding/landing.md) (entry point)
## Edge cases
- Network offline → show offline banner, disable submit
- Email already used → suggest sign in with different account
- Account locked → redirect to [Account Recovery](account-recovery.md)
## Related code
- `lib/features/auth/login_page.dart` — UI tree
- `lib/features/auth/login_controller.dart` — state machine
- `lib/api/auth_service.dart` — network layer
```
## L3 — Feature Doc (Logic / non-UI)
Same frontmatter but `kind: logic`. Sections differ:
```markdown
---
type: og-feature
kind: logic
feature: session-refresh
module: auth
schema: 1
code:
- lib/auth/session_refresh.dart
- lib/api/auth_service.dart
last_synced_commit: <git-sha>
last_reviewed: 2026-05-06
---
# Session Refresh
One-paragraph summary.
## Triggers
When does this run?
- Token < 5 min until expiry → scheduled refresh
- App returns to foreground after backgrounded > 30 min
- Manual refresh via `AuthState.refresh()`
## Inputs
What data does it consume?
- Current `refresh_token` from `TokenStorage`
- Optional `force` flag
## Outputs
What does it produce?
- New `access_token` (15 min lifetime)
- Rotated `refresh_token` (30 day lifetime)
- On failure: emits `auth-expired` event
## Logic flow
Numbered or mermaid flowchart of the steps.
## State
If the logic has internal state machine, document transitions.
## Failure modes
| Failure | Detection | Recovery |
|---------|-----------|----------|
| Refresh token expired | API 401 | Emit auth-expired, force logout |
| Network error | timeout | Backoff retry up to 3x, then auth-expired |
| Server 5xx | API 500 | Same as network error |
## Cross-feature links
- ← [Login](login.md) — initial token issuance
- → [Logout](logout.md) — failure path
## Related code
- `lib/auth/session_refresh.dart`
```
## Frontmatter field reference
| Field | Required | Description |
|-------|----------|-------------|
| `type` | yes | `og-root`, `og-module`, or `og-feature` |
| `schema` | yes | Schema version, currently `1` |
| `kind` | features only | `ui` or `logic` |
| `feature` | features only | Feature slug (kebab-case) |
| `module` | features+modules | Module slug |
| `code` | features only | List of source file paths this doc describes |
| `last_synced_commit` | yes | Git SHA at which doc was last verified against code. Empty string if never synced. |
| `last_reviewed` | features only | ISO date of last human review |
## Drift detection contract
A doc is considered **in drift** if:
1. Any file in `code:` has been modified since `last_synced_commit`, AND
2. The modification was not a pure-refactor / pure-formatting change
The drift-check script reports candidates; humans/AI confirm whether each is
actual drift or noise.
`last_synced_commit: ""` (empty) means the doc has never been synced — it's
either a freshly-stubbed file or a placeholder. The drift checker treats this
as "needs initial sync" rather than drift.
## `.feat-tree.json` schema
Project-root config file written by `/geno-init` and read by hooks /
`/geno-sync`:
| Field | Values | Read by |
|-------|--------|---------|
| `version` | integer (currently `1`) | All consumers |
| `tree_path` | path string, default `"feat-tree"` | `drift-check.sh` |
| `drift_mode` | `"warn"` \| `"block"` | `stop-check.sh` |
| `gen_mode` | `"stub"` \| `"full"` | `/geno-sync` (to distinguish unwritten stubs from unverified full-mode prose) |
## Writing rules
These rules apply to AI agents writing or updating docs:
1. **One feature = one L3 doc.** Don't merge multiple features into one file
"for convenience." If two features always change together, that's a hint
they should be one feature in the tree.
2. **Describe behavior, not implementation.** Avoid pseudocode that mirrors
actual code structure. Code is the source of truth for *how*; docs are
the source of truth for *what* and *why*.
3. **Wireframes for every UI feature.** Even rough ASCII art. The wireframe
anchors the rest of the doc.
4. **Cross-links are one-way assertions.** A doc says "I depend on X" — it
does not promise X agrees. The drift check does not enforce reciprocity;
it's the author's job to keep cross-links consistent.
5. **Limit cross-link depth.** When reading a doc, follow at most one hop of
cross-links by default. Going deeper requires explicit AI judgment that
the deeper context is needed.
6. **Update `last_synced_commit` only when verified.** Bumping the SHA
without actually re-reading code is the failure mode that destroys this
system. If unsure, leave the SHA stale and let drift-check flag it.
7. **No code dumps.** Don't paste blocks of source code into docs.
Reference files in the `code:` frontmatter and the `Related code`
section instead.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 198k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |