docs(specs): Spec H — Life Onboarding & Capability UX#1243
Open
broomva wants to merge 4 commits into
Open
Conversation
Four-phase, 15-sub-phase spec covering the Zero-shaped UX gap surfaced
by the 2026-05-13 zero.xyz architectural deep-dive. Scope:
F.A Bootstrap (F-Sub-A..D) — life init → identity + journal + status + welcome
F.B Custody (F-Sub-E..G) — --custody flag + EncryptedSeed + auto-detection
F.C Capability (F-Sub-H..K) — registry crate + ReviewLedger + PaidCapability
trait + Spaces gossip channel
F.D Operator UX (F-Sub-L..O) — upgrade check + attest/policy/trust + skill
install + lineage wallets
F-Sub-A SHIPPED in #1242. Remaining 14 sub-phases queued for Linear
filing (umbrella + 14 children, blocked-by dependency graph wired).
Total estimate: 45 points across 15 sub-phases. Critical path:
A → B → C → J → H → I (with E in parallel for production deploys).
8 locked decisions inline (L6-F1..F8): single init entry, committable
soul.json, InProcess default but feature-flagged backends, event-sourced
discovery via Lago, deferred-write reviews paired to payments,
PaidCapability sibling of Tool, welcome credit as Haima merchant,
opt-in skill installation.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
You’ve run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughAdded a comprehensive specification document defining "Spec F — Life Onboarding & Capability UX," which outlines four independently shippable phases to compress onboarding into a single ChangesSpec F — Life Onboarding & Capability UX
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~5 minutes Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md`:
- Around line 440-445: Update the spec and installer to use a single canonical
filename and required frontmatter fields: change the canonical skill file
reference to the exact filename used by runtimes (e.g., SKILL.md for
Claude/Codex and skill.md for Cursor) in the spec text and ensure
crates/cli/life-cli/skills/life.md is authored with the required YAML
frontmatter (include at minimum: id, name, version, commands or tools list, and
description) so discovery matches installation; then update
crates/cli/life-cli/src/skill_install.rs to write the correct filename per
runtime (map runtimes to "SKILL.md" or "skill.md" explicitly) and validate or
inject the required frontmatter when writing the file so runtimes will reliably
discover the skill.
- Around line 1-8: The spec addition updates major roadmap/architecture scope
but doesn't sync living docs or add follow-up links; update docs/STATUS.md,
docs/ROADMAP.md, and docs/ARCHITECTURE.md to reflect the new Spec F (2026-05-13)
changes, add explicit cross‑references from the spec file (Spec F — Life
Onboarding & Capability UX) to those docs and to the umbrella issue/PR (`#1242`
and any F‑Sub-* children), and ensure docs/STATUS.md is updated to be the
source-of-truth (including phase, owner, and links) so all three files mirror
the spec and include links back to the spec and sub-phase tickets.
- Line 25: Replace the non-portable local path string
'~/Documents/Zero_xyz_Architecture_Research_20260513/research_report_20260513_zero_xyz_architecture.md'
with a repository-relative path or stable URL (e.g., docs/ or assets/ location
or an external DOI/hosted link) so collaborators and CI can access it; update
the footnote text in specs/2026-05-13-spec-f-onboarding-capability-ux.md where
that path appears and make the same replacement for the other occurrence noted
(around line 545) so both references point to the checked-in doc or public URL.
- Around line 73-101: Add a language identifier (e.g., "text") to the fenced
code blocks that contain the ASCII diagrams (the block beginning with "$ life
init" and the other similar diagram blocks in this spec) so they satisfy
markdownlint MD040; update each opening ``` to ```text for the diagram blocks to
ensure consistent rendering and tooling behavior.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 94fbb5c4-1f38-4b24-b825-e7cec12fb6d9
📒 Files selected for processing (1)
docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md
Comment on lines
+1
to
+8
| # Spec F — Life Onboarding & Capability UX | ||
|
|
||
| **Date**: 2026-05-13 | ||
| **Status**: Draft (Phase F-Sub-A in progress via [#1242](https://github.com/broomva/life/pull/1242); F-Sub-B…O queued) | ||
| **Sibling of**: Spec D §"Trait shape" (custody backends) and Spec C₃ §6.5 (lifegw close codes) | ||
| **Owner**: developer-facing surface (`crates/cli/`, `crates/anima/`, `crates/haima/`, `crates/lago/`, new `crates/capability-registry/`) | ||
| **Linear**: umbrella issue (Urgent, 0 points) with 15 sub-phase children F-Sub-A…O (priorities + estimates inline); filed against the **Life** project on the broomva team after user approval of this spec. | ||
|
|
There was a problem hiding this comment.
Sync living docs alongside this major spec addition.
This introduces major roadmap/architecture scope but does not include corresponding updates (or explicit follow-up links) for docs/STATUS.md, docs/ROADMAP.md, and docs/ARCHITECTURE.md, which risks source-of-truth drift.
As per coding guidelines, "Keep living documentation in docs/ synchronized with actual implementation — update STATUS.md, ROADMAP.md, and ARCHITECTURE.md after major changes" and "treat docs/STATUS.md as source of truth when docs conflict".
Also applies to: 478-496
🧰 Tools
🪛 LanguageTool
[grammar] ~5-~5: Ensure spelling is correct
Context: ...e" (custody backends) and Spec C₃ §6.5 (lifegw close codes) Owner: developer-facin...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md` around
lines 1 - 8, The spec addition updates major roadmap/architecture scope but
doesn't sync living docs or add follow-up links; update docs/STATUS.md,
docs/ROADMAP.md, and docs/ARCHITECTURE.md to reflect the new Spec F (2026-05-13)
changes, add explicit cross‑references from the spec file (Spec F — Life
Onboarding & Capability UX) to those docs and to the umbrella issue/PR (`#1242`
and any F‑Sub-* children), and ensure docs/STATUS.md is updated to be the
source-of-truth (including phase, owner, and links) so all three files mirror
the spec and include links back to the spec and sub-phase tickets.
|
|
||
| This is Spec F: the developer-facing surface that turns Life's substrate advantages into a one-command onboarding story and a Life-native capability discovery layer. | ||
|
|
||
| [^1]: `~/Documents/Zero_xyz_Architecture_Research_20260513/research_report_20260513_zero_xyz_architecture.md` — 10,099-word architectural deep-dive across 27 cited sources, completed 2026-05-13. |
There was a problem hiding this comment.
Replace local filesystem references with repo- or web-accessible references.
~/Documents/... paths are non-portable and effectively broken for collaborators/CI docs consumers. Prefer a checked-in doc path or stable URL.
Also applies to: 545-545
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md` at line
25, Replace the non-portable local path string
'~/Documents/Zero_xyz_Architecture_Research_20260513/research_report_20260513_zero_xyz_architecture.md'
with a repository-relative path or stable URL (e.g., docs/ or assets/ location
or an external DOI/hosted link) so collaborators and CI can access it; update
the footnote text in specs/2026-05-13-spec-f-onboarding-capability-ux.md where
that path appears and make the same replacement for the other occurrence noted
(around line 545) so both references point to the checked-in doc or public URL.
Comment on lines
+73
to
+101
| ``` | ||
| $ life init | ||
| │ | ||
| ├── crates/cli/life-cli/src/init.rs::run_in(&root) | ||
| │ │ | ||
| │ ├─→ create_life_dir(.life/, .life/control/, .life/identity/) | ||
| │ ├─→ write_config(.life/config.toml) ← idempotent | ||
| │ ├─→ write_policy(.life/control/policy.yaml) | ||
| │ ├─→ bootstrap_anima_identity(life_dir) | ||
| │ │ │ | ||
| │ │ ├─→ MasterSeed::generate() | ||
| │ │ ├─→ InProcessAnima::from_seed_arc(seed) | ||
| │ │ ├─→ SoulBuilder::new(name, mission, auth_pubkey).build() | ||
| │ │ ├─→ write_seed(.life/identity/seed.local.bin, 0o600) | ||
| │ │ └─→ write_soul_document(.life/identity/soul.json) | ||
| │ ├─→ bootstrap_lago_journal(life_dir) ← F-Sub-B | ||
| │ │ │ | ||
| │ │ ├─→ open redb at .life/journal/events.redb | ||
| │ │ ├─→ create_genesis_event(&soul) ← anima-lago | ||
| │ │ └─→ append AnimaEventKind::SoulGenesis | ||
| │ ├─→ claim_welcome_credit(wallet_address)? ← F-Sub-D (opt-in) | ||
| │ │ │ | ||
| │ │ └─→ POST https://merchants.broomva.tech/welcome/claim | ||
| │ │ body: { wallet, walletSignature } | ||
| │ │ returns: { credit_micro_credits, tx_hash } | ||
| │ └─→ update_gitignore(root) | ||
| │ | ||
| └─→ exits with: did:key:zDn..., 0x..., $X welcome credit applied | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
The fenced blocks starting at Line 73, Line 105, Line 153, and Line 501 should declare a language (for example text) to satisfy markdownlint and keep rendering/tooling consistent.
Also applies to: 105-129, 153-177, 501-505
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 73-73: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md` around
lines 73 - 101, Add a language identifier (e.g., "text") to the fenced code
blocks that contain the ASCII diagrams (the block beginning with "$ life init"
and the other similar diagram blocks in this spec) so they satisfy markdownlint
MD040; update each opening ``` to ```text for the diagram blocks to ensure
consistent rendering and tooling behavior.
Comment on lines
+440
to
+445
| **Scope**: On explicit `life init --install-skills` or `life setup` prompt, write a `life` skill (a SKILL.md frontmatter file) to the relevant agent runtime directories so Claude Code, Cursor, Codex, and Windsurf can pick up the `life` command surface without manual configuration. Implements L6-F8. | ||
|
|
||
| **Deliverables**: | ||
| - `crates/cli/life-cli/skills/life.md` — the canonical skill content (commands, examples, when-to-use guidance) | ||
| - `crates/cli/life-cli/src/skill_install.rs` — writes the skill to the right path per runtime: `~/.claude/skills/life/SKILL.md`, `~/.cursor/skills/life/skill.md`, `~/.codex/skills/life/SKILL.md`, etc. | ||
| - Detection: skip runtimes that aren't installed (no auto-discovery surprise) |
There was a problem hiding this comment.
Clarify canonical skill file contract to prevent discovery mismatch.
Line 443 declares canonical content as skills/life.md, while install targets use SKILL.md/skill.md; also, the spec should explicitly require YAML frontmatter fields for discovery so implementation is unambiguous.
As per coding guidelines, "SKILL.md discovery in Praxis uses YAML frontmatter to register tools and capabilities".
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/superpowers/specs/2026-05-13-spec-f-onboarding-capability-ux.md` around
lines 440 - 445, Update the spec and installer to use a single canonical
filename and required frontmatter fields: change the canonical skill file
reference to the exact filename used by runtimes (e.g., SKILL.md for
Claude/Codex and skill.md for Cursor) in the spec text and ensure
crates/cli/life-cli/skills/life.md is authored with the required YAML
frontmatter (include at minimum: id, name, version, commands or tools list, and
description) so discovery matches installation; then update
crates/cli/life-cli/src/skill_install.rs to write the correct filename per
runtime (map runtimes to "SKILL.md" or "skill.md" explicitly) and validate or
inject the required frontmatter when writing the file so runtimes will reliably
discover the skill.
Companion file to 2026-05-13-spec-f-onboarding-capability-ux.md with 16 paste-ready ticket bodies (1 umbrella + 15 sub-phases F-Sub-A..O). Follows the format established by 2026-05-07-spec-e-linear-tickets-draft.md. Linear MCP token expired mid-flow; once re-authorized, file in the order specified in §Filing Order so blocked-by edges resolve on first save. Cross-references PR #1242 (F-Sub-A implementation, to mark Done) and PR #1243 (this spec). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…026-05-11 Spec F) The 2026-05-11 cycle established Spec F (subscription auth + Tier-1 agent invocation, under the Techne project, BRO-1042 umbrella) and Spec G (external trigger ingress). My new spec collides with that Spec F. Next free letter is H. Renamed everywhere: - Filenames: 2026-05-13-spec-f-* → 2026-05-13-spec-h-* - Title: "Spec F — Life Onboarding & Capability UX" → "Spec H — ..." - Locked decisions: L6-F1..F8 → L6-H1..H8 - Sub-phases: F-Sub-A..O → H-Sub-A..O (15 letters) - Phase groupings: F.A/F.B/F.C/F.D → H.A/H.B/H.C/H.D Branch name kept as docs/spec-f-* (transient artifact; doesn't affect the canonical file contents). PR title + body updated in a follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
broomva
changed the title
…1..1126 filed All 16 tickets shipped to Linear under the Life project: - Umbrella: BRO-1111 (Spec H — Life Onboarding & Capability UX) - H-Sub-A: BRO-1112 (Done, links #1242) - H-Sub-B: BRO-1113 H-Sub-I: BRO-1124 - H-Sub-C: BRO-1117 H-Sub-J: BRO-1114 - H-Sub-D: BRO-1118 H-Sub-K: BRO-1126 - H-Sub-E: BRO-1119 H-Sub-L: BRO-1115 - H-Sub-F: BRO-1120 H-Sub-M: BRO-1121 - H-Sub-G: BRO-1122 H-Sub-N: BRO-1116 - H-Sub-H: BRO-1125 H-Sub-O: BRO-1123 Total: 45 points across 15 sub-phases, blocked-by graph wired. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Spec H: four-phase, 15-sub-phase roadmap covering the developer-facing UX gap surfaced by the 2026-05-13 zero.xyz architectural deep-dive (
~/Documents/Zero_xyz_Architecture_Research_20260513/).Renamed from Spec F → Spec H (Spec F + G are taken by the 2026-05-11 cycle — subscription-auth-tier-1 + external-trigger-ingress under the Techne project, BRO-1042 umbrella).
life init→ identity + journal +life status+ welcome credit--custody=flag +EncryptedSeedat rest + runtime auto-detectioncapability-registrycrate +ReviewLedgerport +PaidCapabilitytrait + Spaces gossiplife upgrade check+ identity attest/policy/trust CLI + skill installation + lineage walletsTotal: ~45 points across 15 sub-phases. H-Sub-A SHIPPED in #1242. Critical path: A → B → C → J → H → I (E in parallel for production).
Locked decisions (8 inline as L6-H1..H8)
Single
life initentry point, committablesoul.json, InProcess as default but every Spec D backend behind a Cargo feature, event-sourced discovery via Lago (no separate registry table), deferred-write reviews paired to payment events by ULID,PaidCapabilityas a sibling ofTool(not a wrapper), welcome credit as a Haima merchant (consistent financial state projection), skill installation opt-in only.Files
docs/superpowers/specs/2026-05-13-spec-h-onboarding-capability-ux.md— spec doc (548 lines)docs/superpowers/specs/2026-05-13-spec-h-linear-tickets-draft.md— paste-ready ticket bodies, soon SUPERSEDED once tickets landWhat this PR is
Just the spec doc + companion. Implementation work is tracked through Linear tickets (umbrella + 14 children) — filing now.
Test plan
life init#1242)🤖 Generated with Claude Code