yam-flow 0.1.0

package/AGENTS.md

@@ -0,0 +1,18 @@
+# yam Core Rules
+
+1. Direction before execution.
+2. Start fast, then deepen deliberately when scope, risk, or user intent calls for it.
+3. Treat token economy as part of quality.
+4. Reuse project context packs before broad reading.
+5. Read only the context needed for the requested change.
+6. Check local project fit before changing code, even for small work.
+7. Prefer existing project patterns over new abstractions.
+8. Make the smallest useful change.
+9. Verify at the lightest level that honestly supports the claim, then escalate verification when the claim is larger.
+10. Report skipped, partial, blocked, or assumed verification plainly.
+11. Do not run broad tests for tiny changes, but do not under-verify risky changes.
+12. Do not use teams, orchestration, structured proof, or tmux unless risk, user intent, or an approved route justifies it.
+13. Escalate risky work by asking or recommending, not by silently switching modes.
+14. For UI work, inspect real states and responsive behavior when feasible.
+15. For long-running processes, do not claim cleanup unless process exit is checked.
+16. Keep final reports short and concrete.

package/COMMANDS.md

@@ -0,0 +1,152 @@
+# yam Commands
+
+Use these as prompt commands in Codex after restarting the app.
+
+## Quick
+
+```text
+$quick
+회원가입 버튼 padding을 2px 늘리고 라벨을 "Start free"로 바꿔줘.
+프로젝트 방향성과 기존 버튼 패턴에 맞게 최소 수정만 해줘.
+```
+
+```text
+$quick
+현재 빌드/타입 에러를 빠르게 스캔하고,
+가장 작은 원인부터 하나씩 고쳐줘.
+검증은 관련 명령만 실행해줘.
+```
+
+## Ueye
+
+```text
+$ueye
+첨부한 레퍼런스 이미지의 분위기를 참고해서 가격 카드 UI를 고급스럽게 개선해줘.
+구현 전에 레퍼런스에서 읽은 디자인 특징을 짧게 증명하고,
+구현 후 레퍼런스와 결과물을 비교해서 비슷한 점과 다른 점을 정리해줘.
+이 프로젝트의 디자인 방향성과 맞게 구현하고,
+가능하면 기본/모바일/오류 상태를 실제 화면 기준으로 확인해줘.
+```
+
+```text
+$ueye
+이 스크린샷을 UX/UI 관점에서 봐줘.
+방향성, CTA, 대비, 정렬, spacing, 모바일 리스크를 P0-P3로 정리하고,
+가능한 안전한 수정안을 제안해줘.
+```
+
+```text
+yam template ueye-comparison
+```
+
+## Review-Only
+
+```text
+$deep
+현재 변경사항을 리뷰해줘.
+방향성, 코드 리스크, 검증 부족을 P0-P3로 정리하고 수정은 하지 마.
+```
+
+## Question
+
+```text
+$question
+tmux가 무엇이고, 지금 내 작업에 꼭 필요한지 짧게 설명해줘.
+구현이나 넓은 조사는 하지 말고 바로 답해줘.
+```
+
+## Deep
+
+```text
+$deep
+결제 플로우 상태 처리를 안정화해줘.
+성공/실패/로딩/재시도 상태와 회귀 위험까지 깊게 검증해줘.
+필요하면 tmux/dev server/browser QA/cleanup proof까지 사용해줘.
+```
+
+## Mission
+
+```text
+$mission
+아래 구현 계획은 확정됐어.
+
+목표:
+-
+
+범위:
+-
+
+금지사항:
+-
+
+Acceptance criteria:
+-
+
+실제 subagent/team 단위로 구현하고,
+implementer/reviewer/UX verifier/doctor lane으로 교차 검증해줘.
+필요하면 tmux/dev server/browser QA/cleanup proof까지 포함해줘.
+최종 보고에는 evidence, truth status, cleanup status, fix-first items, remaining tasks를 포함해줘.
+```
+
+## Scout
+
+```text
+$scout
+Next.js에서 이 기능을 구현하는 가장 안전한 방식을 찾아줘.
+공식 문서와 신뢰 가능한 근거 중심으로 보고,
+객관적 판단과 주관적 판단, 현실적/미래적 관점까지 나눠서 추천해줘.
+코드는 아직 수정하지 마.
+```
+
+## Project Pack
+
+Use the CLI to create and inspect the small project direction file.
+
+```bash
+yam init-project /path/to/project
+yam pack /path/to/project
+yam template mission
+```
+
+## Memory
+
+Use this only when a lesson should survive across sessions.
+
+```bash
+yam memory init /path/to/project
+yam memory add /path/to/project --kind repeat_mistake --summary "UI work was declared done without visual review" --evidence "Missed spacing regression" --action "Run $ueye after major UI work"
+yam memory summary /path/to/project
+```
+
+## Token Budget
+
+```bash
+yam budget quick
+yam measure quick --files 3 --commands 1 --report-lines 5 --seconds 40
+```
+
+## Tool Doctor / Proof / Safety
+
+Read-only readiness and evidence helpers. These do not install, deploy, query databases, or run verification by themselves.
+
+```bash
+yam tools doctor /path/to/project
+yam tools doctor /path/to/project --json
+yam proof /path/to/project
+yam proof --route deep --truth verified --command "npm run build: pass"
+yam proof --route ueye --truth verified --visual "reference image only"
+yam proof --route deep --truth proven --require-runtime --runtime "mock server fixture"
+yam proof write /path/to/project --route deep --truth partial --command "npm run build: pass"
+yam proof write /path/to/project --format md --truth assumed --assumption "No runtime was started"
+yam safety "supabase db reset --linked"
+```
+
+## Lite Hook
+
+Advisory-only hook. It does not run checks or force routes.
+
+```bash
+yam hook status --global
+yam hook enable lite --global
+yam hook disable lite --global
+```

package/DECISIONS.md

@@ -0,0 +1,70 @@
+# yam Decision Baseline
+
+Every `yam` change is evaluated against strict proof, modular skill, and minimal-core harness principles.
+
+## Fixed Questions
+
+1. What needs concrete evidence before completion?
+2. What should stay selective or low-context?
+3. What can be removed to keep the core obeyable?
+4. What should `yam` keep light by default, and what should deepen deliberately?
+
+## Keep
+
+### Strict Proof
+
+- Truthful completion language.
+- Risk escalation.
+- Bounded verification.
+- Fake versus real distinction.
+- Runtime/process proof only when explicitly requested.
+
+### Modular Skills
+
+- Skills-first structure.
+- Selective install.
+- Low-context and no-hooks path.
+- Token optimization.
+- Project-specific rules instead of global bloat.
+
+### Minimal Core
+
+- Short core.
+- Few route names.
+- Minimal context.
+- Rules the model can actually follow.
+
+## Reject
+
+### From Strict Proof
+
+- Mandatory hooks.
+- Mandatory Team or subagent proof.
+- Always-on tmux/proof lifecycle.
+- Heavy memory systems for ordinary edits.
+
+### From Modular Skills
+
+- Full install by default.
+- Giant catalog context.
+- Hook runtime by default.
+- Too many always-on rules.
+
+### From Minimal Core
+
+- Under-verification.
+- Vague quality rules.
+- No route structure for risky work.
+
+## yam Standard
+
+```text
+Direction before execution.
+Context-reuse first.
+Token-aware by default.
+Start fast.
+Deepen deliberately.
+Basic direction fit and honest verification always.
+Honest by design.
+Heavy proof when risk or user intent calls for it.
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0kim0bos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,174 @@
+# yam
+
+`yam` is a progressive proof-first personal agent flow for fast product building, high-quality UI work, and honest verification.
+
+```text
+Direction before execution.
+Start fast.
+Deepen deliberately.
+Basic direction fit and honest verification always.
+Honest by design.
+Heavy proof when risk or user intent calls for it.
+Token-aware by default.
+Context-reuse first.
+End with remaining tasks and fix-first items.
+```
+
+## Routes
+
+- `$quick`: fast scoped implementation, small fixes, and quick error scans.
+- `$ueye`: tight UI/UX/design implementation and visual review with reference-read proof, comparison, and quality judgment.
+- `$question`: direct Q&A without turning simple questions into research projects.
+- `$scout`: bounded investigation and recommendation.
+- `$deep`: single-agent heavy verification by request, including runtime/tmux/browser/process proof when needed.
+- `$mission`: approved-plan execution with real subagent/team lanes, cross-verification, doctor scan, and final proof.
+
+See `COMMANDS.md` for copy-ready examples.
+See `ROADMAP.md` for remaining implementation stages.
+
+## Defaults
+
+- No hooks.
+- Optional `yam-lite` hook is advisory-only and off by default.
+- No automatic Team routing.
+- No automatic proof loops.
+- No automatic tmux.
+- No false completion claims: verification, cleanup, and visual checks must match actual evidence.
+- `yam` is not lightweight-only; it is progressive: quick entry, stronger proof as scope/risk grows.
+- Every route should check project direction and use an honest verification level.
+- Small work stays small, but serious work is allowed to become serious.
+- Token economy is part of quality.
+- Project packs prevent re-reading and re-planning from scratch.
+- Memory is opt-in, project-local, and sparse.
+- Final reports should compactly mention remaining tasks and fix-first issues when useful.
+
+## Project Pack
+
+For repeated work in a project, add a small `yam.project.md` at the project root.
+
+```bash
+yam init-project .
+yam pack .
+```
+
+Routes should read this pack before broad project exploration. The pack is user-owned and should stay compact: `yam` creates it only when missing, checks it with `pack`, and avoids automatic rewrites.
+
+## Memory
+
+For repeated mistakes, wrong decisions, direction changes, or durable lessons, use opt-in project memory.
+
+```bash
+yam memory init .
+yam memory add . --kind lesson --summary "Keep UI checks visual before declaring done" --action "Use $ueye after major UI changes"
+yam memory summary .
+```
+
+Memory writes to `.yam/memory/` only when you run the command. Routes should prefer `.yam/memory/summary.md` and should not read every record by default.
+
+## Lite Hook
+
+`yam-lite` can be enabled when you want a tiny route/direction nudge in every prompt without automatic checks or proof gates.
+It is only the always-on entry layer, not the full ambition of `yam`.
+
+```bash
+yam hook status --global
+yam hook enable lite --global
+yam hook disable lite --global
+```
+
+It only adds short advisory context. It does not run verification, tmux, browser QA, subagents, or dependency installs.
+
+## Install
+
+Recommended:
+
+```bash
+cd ~/Documents/Codex/tools/yam
+yam install
+```
+
+This copies each skill plus the shared `references/` directory into `~/.agents/skills/`, which is the user skill root used by this Codex desktop setup.
+
+Manual install is also possible by copying selected skill folders into your active Codex user skill root, but make sure each installed skill also receives a `references/` folder.
+
+Recommended v0:
+
+```bash
+mkdir -p ~/.agents/skills
+for skill in quick ueye question scout deep mission; do
+  rm -rf "$HOME/.agents/skills/$skill"
+  mkdir -p "$HOME/.agents/skills/$skill"
+  cp "skills/$skill/SKILL.md" "$HOME/.agents/skills/$skill/SKILL.md"
+  cp -R references "$HOME/.agents/skills/$skill/references"
+done
+```
+
+Restart Codex after installing so skills reload.
+
+## Uninstall
+
+```bash
+cd ~/Documents/Codex/tools/yam
+yam uninstall
+```
+
+No hooks, automations, or global config files are installed.
+
+## Manage
+
+```bash
+yam list
+yam status
+yam verify
+yam doctor
+yam tools doctor /path/to/project
+yam tools doctor /path/to/project --json
+yam proof /path/to/project
+yam proof write /path/to/project --route quick --truth verified --command "npm run verify:self: pass"
+yam proof --route ueye --truth verified --visual "reference image only"
+yam safety "supabase db reset"
+yam detect /path/to/project
+yam pack /path/to/project
+yam hook status --global
+yam hook enable lite --global
+yam hook disable lite --global
+yam budget ueye
+yam measure ueye --files 5 --commands 2 --report-lines 12 --seconds 180
+yam template ueye
+yam template ueye-comparison
+yam template mission
+yam template proof
+yam tune-log /path/to/project
+yam memory list /path/to/project
+yam memory summary /path/to/project
+yam examples
+yam path
+yam version
+yam init-project /path/to/project
+```
+
+## npm / npx Prep
+
+The package exposes the `yam` binary. It does not mutate your home directory during package installation.
+
+```bash
+npx -y --package yam-flow yam list
+npx -y --package yam-flow yam install
+npm install -g yam-flow
+yam status
+```
+
+Publishing still requires confirming the final npm package name and account access.
+
+## Trust Kernel
+
+`yam` includes a small local trust kernel:
+
+- completion proof shape
+- truth caps
+- fake versus real distinction
+- runtime truth matrix
+- visual evidence caps
+- DB/Supabase safety signals
+
+It is implemented locally in `src/lib/trust-kernel.ts` and kept route-scoped. It is not an always-on release gate.