Skip to content

Integrate koni-docs standard#5000

Open
saltict wants to merge 29 commits into
subwallet-devfrom
ai-development
Open

Integrate koni-docs standard#5000
saltict wants to merge 29 commits into
subwallet-devfrom
ai-development

Conversation

@saltict
Copy link
Copy Markdown

@saltict saltict commented Jun 2, 2026

Summary

  • Install koni-docs skill from Koniverse/Koni-Skills into the monorepo (skills-lock.json + .agents/skills/koni-docs/).
  • Add AGENTS.md (canonical AI agent guide — single source of truth for Cursor / Gemini / Codex CLI / Claude Code).
  • Add CLAUDE.md (thin pointer to AGENTS.md + Koni-Docs Integration YAML block + Active Context).
  • Add VERSION file (1.3.79, synced with root package.json).
  • Add .active-context.example.md (per-developer Pattern B template); gitignore .active-context.md.

This is sub-task 1 of 3 on the ai-development umbrella. Out of scope (separate PRs to follow):

  • Sub-task 2: standardize docs/ content (BRIEF / PRD / ARCHITECTURE / CONTEXT / LESSONS / SETUP / sprints / CHANGELOG).
  • Sub-task 3: migrate GitHub issues to koni-docs stories / epics format.

Spec & plan

  • Design spec: docs/superpowers/specs/2026-06-02-koni-docs-integration-design.md
  • Implementation plan: docs/superpowers/plans/2026-06-02-koni-docs-integration-sub-task-1.md

Test plan

  • npx skills experimental_install reproduces .agents/skills/koni-docs/ from skills-lock.json (round-trip MATCH, byte-for-byte identical)
  • .active-context.md is gitignored (git check-ignore confirms rule at .gitignore:49)
  • No placeholder leakage in AGENTS.md / VERSION / .active-context.example.md (grep for <MONOREPO_TABLE_ROWS>, <TODO>, XXX-FIXME, fill in → no matches)
  • yarn install --immutable succeeds (~10 s, lockfile unchanged)
  • yarn koni-dev-build-ts (TypeScript build) succeeds
  • CLAUDE.md ## Koni-Docs Integration block parses as valid YAML with expected fields (plugins: [], docs_path: docs/, active_sprint: <TBD-after-sub-task-2>, version_file: VERSION)
  • AGENTS.md Section 4 commands verified to exist in root package.json (fixed in commit 76ff80b6f0 — original draft had 4 fabricated webpack:* aliases; replaced with real script names build:ui, watch-dev, webapp:dev, webapp:build, plus 2 new web-runner rows)
  • AGENTS.md has 10 H2 sections, 12 monorepo package rows

Known deferred items

  • koni-docs RULE-1 / RULE-2 (VERSION + CHANGELOG in same commit) enforcement is deferred until sub-task 2 creates docs/CHANGELOG.md.
  • packages/* use version 1.3.79-1 (with -1 monorepo internal suffix); VERSION uses 1.3.79 (root). Reconciliation deferred to sub-task 2.
  • active_sprint: in CLAUDE.md is <TBD-after-sub-task-2> — no active sprint until sub-task 2 starts one.
  • Root-level yarn run lint OOMs locally on the implementing machine due to a pre-existing heap limit; this is unrelated to this PR (CI is expected to run lint successfully).

Brainstorming + plan trail

Implementation followed the Superpowers brainstorming → writing-plans → subagent-driven-development flow. Spec + plan files are committed in docs/superpowers/. Every task went through two-stage review (spec compliance → code quality) before its commit was accepted. The only review iteration was Task 6 → fix commit 76ff80b6f0 (Section 4 fabricated commands).

🤖 Generated with Claude Code

saltict and others added 8 commits June 2, 2026 17:04
@saltict
docs: add koni-docs integration design spec (sub-task 1)
6e04c13 
Brainstorming output for ai-development branch. Covers scope decomposition
(1 of 3 sub-tasks), file inventory, content shape, execution workflow,
risks, and out-of-scope items deferred to sub-task 2 (docs content) and
sub-task 3 (issue migration).
@saltict
docs: add implementation plan for koni-docs integration (sub-task 1)
c8461b5
@saltict
chore: install koni-docs skill from Koniverse/Koni-Skills
29134db
@saltict
chore: add VERSION file and gitignore active-context
094e5d5
@saltict
docs: add active-context example template (koni Pattern B)
a1210d8
@saltict
docs: add AGENTS.md (canonical AI agent guide for SubWallet)
3365b4a
@saltict @claude
fix: correct yarn commands in AGENTS.md (use real package.json scripts)
76ff80b 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
@saltict
docs: add CLAUDE.md pointer with koni-docs integration block
7a49a00
@saltict
Copy link
Copy Markdown
Author

saltict commented Jun 2, 2026 •
edited
Loading

🚀 Deployed on https://pr-5000--sw-web-runner.netlify.app

@saltict saltict temporarily deployed to pull request June 2, 2026 11:11 Inactive
@saltict
docs: add AI coding behavior guidelines as section 1 of AGENTS.md
821bb9e 
Adapted from multica-ai/andrej-karpathy-skills CLAUDE.md. Adds 4 rules
(Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven
Execution) at the top so AI agents see them before project-specific
context. Existing sections renumbered 1-10 -> 2-11; no content changes.
@saltict saltict temporarily deployed to pull request June 3, 2026 03:27 Inactive
@saltict saltict changed the title chore: integrate koni-docs skill + AGENTS/CLAUDE.md (sub-task 1) Integrate koni-docs standard Jun 3, 2026
@saltict saltict temporarily deployed to pull request June 3, 2026 07:43 Inactive
tunghp2002 and others added 10 commits June 3, 2026 17:35
@tunghp2002 @claude
docs: a6-setup — add docs/SETUP.md (dev environment)
eace537 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a7-changelog — add [Unreleased] anchor to CHANGELOG.md
c646536 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a3-arch — add docs/ARCHITECTURE.md with AD table
2d336e5 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a4-context — seed docs/CONTEXT.md decision log from history
47d0cc8 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a5-lessons — seed docs/LESSONS.md from incident history
e9ccbab 
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: fix Mermaid node/subgraph id collision in migration spec
26bfaa3 
WAVE 4/5 subgraphs reused ids W4/W5 as node ids, breaking the
Mermaid render. Rename the nodes to W4N/W5N and update the wave
classDef list.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a4-context — retitle Phase 3 to match its decisions
3af7d22 
Phase 3 header read "Bitcoin, Cardano, Multi-chain Ecosystem" but its
entries (D26-D30) are all swap/XCM scope decisions: cancel dynamic swap
pairs, cancel 1inch, stay on ParaSpell, migrate ParaSpell v1, remove the
Crowdloans tab. Retitle to "Swap/XCM Consolidation & Feature Pruning" so
the phase name matches the decisions it groups.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a4-context — retitle Phase 2 to cover its actual decisions
c478d54 
Phase 2 header said "Earning, Swap, and Multi-chain Expansion" but it
has no swap decision (those are Phase 3) and omitted D21 Texterify (i18n)
and D22 Meld (fiat on-ramp). Retitle to "Earning Rebrand, XCM Bridge,
i18n & Fiat Tooling" so the name covers D20-D25.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a4-context — add 29 chain/account decisions, rebuild into 5 phases
908a04f 
Intake-B only flagged explicitly-worded decisions, so major integrations
(BTC, TON, Cardano, Bittensor, proxy, multisig) had 0 CONTEXT entries
despite being large feature areas — while trivial items like the
Crowdloans removal were captured. Per the koni-docs definition (an
architecture or scope decision / "why we picked X over Y"), mined the
real architecture/scope decisions for those areas from issues/PRs/
comments and merged them with the existing 30.

Result: 30 -> 59 decisions, renumbered D1-D59 chronologically, re-bucketed
into 5 phases with content-accurate titles. New-decision versions resolved
from the CHANGELOG issue->version map. All bodies preserved verbatim.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a3-arch — add AD-11..AD-19 for chain integrations & account models
43e874c 
The AD table only had infra decisions (storage, ChainService, MV3,
keyring, monorepo, XCM toggle, fork). The major chain integrations
(Bitcoin, TON, Cardano, Bittensor) and account models (unified, proxy,
multisig) had no AD entry despite being core architecture — the same
gap just fixed in CONTEXT. Add AD-11..AD-19, each cross-referencing the
CONTEXT decision(s) and source issues.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a4-context — remove leaked group headers + collapse duplicate s…
a5eebf4 
…eparators

The decision-mining agents had emitted area group headers (## TON,
## Multisig Decisions) inside their files; the merge swept them into the
output, and every phase boundary carried a doubled --- (decision trailer
+ phase leader). Strip the stray ## headers (keeping only ## Phase) and
collapse adjacent --- separators. Decision bodies and D1-D59 unchanged.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@saltict saltict temporarily deployed to pull request June 4, 2026 04:43 Inactive
tunghp2002 and others added 2 commits June 4, 2026 17:01
@tunghp2002 @claude
docs: a1-brief — synthesize docs/BRIEF.md from canonicals
666217a 
8-section brief from vision-and-strategy + product-history. Persona uses
the 4 positioning-inferred personas (marked pending product validation);
Success Criteria marked pending product input (no KPIs in source corpus).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a2-prd — add docs/PRD.md (90 FR / 20 NFR + 19-epic index)
32e470c 
Functional + Non-Functional Requirements tables and the Epics & User
Stories index (one epic per approved taxonomy area, EPIC-1..EPIC-19).
FRs resolved shipped-vs-planned per spec resolution rule (79 shipped /
11 planned). Epic story rows left for Stream B.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a2-prd — add FR-91 custom token import (close token-management …
26042d6 
…gap)

G1 re-review surfaced 24 history entries under provisional area
`token-management` (ERC-20/PSP-22 import, enable/disable, display order)
with no FR owner. Folded into chain-management per the split-by-service
rule (AssetRegistry lives in ChainService) and added FR-91 (shipped) to
the chain-management epic (EPIC-4).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@saltict saltict temporarily deployed to pull request June 4, 2026 11:11 Inactive
tunghp2002 and others added 4 commits June 4, 2026 18:46
@tunghp2002 @claude
docs: a4-context — add Phase 5 (D60-D65) from Notion product reports
9c00a28 
Recovered six shipped decisions under-represented in the issue-derived
history (landed as backend/proxy work): D60 backend fee-params + FeeService,
D61 non-native fee via assetConversion on Asset Hub, D62 Coinbase secure-init,
D63 KyberSwap slippage/Degen adaptation, D64 XCM source/delivery fee model,
D65 WalletConnect Connection (pair+session) model. All cross-checked to real
GitHub issues.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a3-arch — add runtime-lifecycle section + AD-20..23 (verified v…
af741cf 
…s code)

Adds a "Runtime lifecycle & service coordination" subsection (4-state MV3
lifecycle, heartbeat, EventService wait-promises/lazy-batch, 3-service
transaction subsystem) and AD-20 (MV3 lifecycle), AD-21 (per-ecosystem
RequestService handlers), AD-22 (EarningService pool-handler tree),
AD-23 (web-runner-cron static-data caching). Every symbol cross-checked
against packages/extension-base + extension-koni source.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a5-lessons — add lessons 35-40 from Notion engineering reports
4319873 
MV3 RAM-vs-responsiveness cost (35), Chrome permission-increase auto-disable
(36), WalletConnect dashboard registration (37), WASM/native-lib mobile
web-runner gating via Cardano break (38), static-content publish param
validation (39), chain-connector (Dedot) parallel-stack + per-chain gating
(40).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@tunghp2002 @claude
docs: a6-setup — add related-repos & release processes from Notion re…
a2c7578 
…ports

Section 7: SubWallet-ChainList (Vite+Nx build migration, version/patch
release flow, required Strapi fields), Static-Content publish discipline,
web-runner update checklist, i18n text→key pipeline, and subwallet:// QA
deep links. Reference renumbered to §8.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@saltict saltict temporarily deployed to pull request June 4, 2026 12:05 Inactive
@tunghp2002 @claude
docs: a1-brief — add traction proxies to Success Criteria, fix person…
cde55af 
…a ranking

- Success Criteria: add public traction metrics (live Chrome Web Store
  figures as of 2026-06, v1.3.80) as point-in-time proxies, plus
  candidate KPI directions; keep "internal KPIs pending product input"
- Who This Serves: correct Primary/Secondary to co-primary — Polkadot
  persona is the anchor by public branding, multi-chain DeFi is the
  growth direction (verified against Chrome Web Store listing title)
- Scope: note the 200+ vs 150+ networks count discrepancy across
  SubWallet's own pages

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
@saltict saltict temporarily deployed to pull request June 5, 2026 05:23 Inactive
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@saltict @tunghp2002