youmd 0.6.21 → 0.6.27

package/examples/youstack-personal/tests/smoke.md

@@ -0,0 +1,9 @@
+# Smoke Test
+
+Read-only checks:
+
+- Parse `youstack.json`.
+- Verify required files exist.
+- Confirm declared capabilities are routable.
+- Confirm host adapter paths are safe relative paths.
+- Do not mutate brain data, connected tools, or repo files.

package/examples/youstack-personal/workflows/startup.md

@@ -0,0 +1,7 @@
+# Startup Workflow
+
+1. Inspect the stack manifest.
+2. Confirm host adapter and project context availability.
+3. Read local public/static context.
+4. Fetch protected context only through scoped You.md API/MCP grants.
+5. State the next useful move and the boundaries before acting.

package/examples/youstack-personal/youstack.json

@@ -0,0 +1,123 @@
+{
+  "schemaVersion": "youstack/v1",
+  "kind": "youstack",
+  "slug": "personal-agent-start",
+  "name": "Personal Agent Start",
+  "domain": "personal-agent-ops",
+  "aliases": ["startup", "agent-start", "default-personal-stack"],
+  "tags": ["coding", "project-context", "agent-startup"],
+  "version": "0.1.0",
+  "description": "Local-first starter YouStack for Claude Code, Codex, and Cursor.",
+  "visibility": "private",
+  "compatibility": {
+    "hosts": ["claude-code", "codex", "cursor"],
+    "minYoumdCli": "0.6.0",
+    "requiresYoumdApi": false,
+    "requiresYoumdMcp": false
+  },
+  "brainScopes": [
+    {
+      "scope": "identity.public.read",
+      "required": true,
+      "reason": "Introduce the user and their working style to the host agent."
+    },
+    {
+      "scope": "preferences.agent.read",
+      "required": true,
+      "reason": "Apply communication, coding, and collaboration preferences."
+    },
+    {
+      "scope": "memories.search",
+      "required": false,
+      "reason": "Retrieve protected memories only when local static files are insufficient."
+    }
+  ],
+  "files": [
+    {
+      "path": "skills/youstack-start/SKILL.md",
+      "type": "skill",
+      "required": true
+    },
+    {
+      "path": "workflows/startup.md",
+      "type": "workflow",
+      "required": true
+    },
+    {
+      "path": "docs/quickstart.md",
+      "type": "docs",
+      "required": false
+    },
+    {
+      "path": "tests/smoke.md",
+      "type": "test",
+      "required": false
+    }
+  ],
+  "adapters": {
+    "claude-code": {
+      "files": [".claude/skills/youstacks/personal-agent-start/SKILL.md"],
+      "bootstrap": "CLAUDE.md"
+    },
+    "codex": {
+      "files": [".codex/skills/youstacks/personal-agent-start/SKILL.md"],
+      "bootstrap": "AGENTS.md"
+    },
+    "cursor": {
+      "files": [".cursor/rules/youstacks-personal-agent-start.md"],
+      "bootstrap": ".cursor/rules"
+    }
+  },
+  "capabilities": [
+    {
+      "id": "startup",
+      "intent": "Load local identity, project context, active requests, TODOs, and host-safe next moves.",
+      "workflow": "workflows/startup.md",
+      "skill": "youstack-start",
+      "localOnly": true,
+      "mutationPolicy": "read_only"
+    },
+    {
+      "id": "protected-memory-search",
+      "intent": "Search protected You.md memories through shared API/MCP when the local stack lacks enough context.",
+      "mcpTool": "you.search_memories",
+      "apiEndpoint": "POST /api/v1/stacks/{stack_id}/brain/search",
+      "requiredScopes": ["memories.search"],
+      "mutationPolicy": "read_only"
+    }
+  ],
+  "accessPolicy": {
+    "defaultMode": "local_static",
+    "protectedByDefault": true,
+    "requiresApprovalFor": ["brain.write", "private_context.read", "connected_tool.write"]
+  },
+  "sharing": {
+    "allowedModes": ["private", "scoped-link", "public-open"],
+    "defaultMode": "private"
+  },
+  "repoSync": {
+    "enabled": false,
+    "provider": "github",
+    "path": "stacks/personal-agent-start"
+  },
+  "docs": {
+    "quickstart": "docs/quickstart.md"
+  },
+  "tests": {
+    "smoke": "tests/smoke.md"
+  },
+  "improvement": {
+    "mode": "propose",
+    "cadence": "after each meaningful agent session",
+    "signals": ["usage", "failures", "user corrections", "repo diffs", "smoke results"],
+    "evals": ["youmd stack smoke", "route startup requests to the expected capability"],
+    "appliesTo": ["skills", "workflows", "docs", "examples", "adapters"],
+    "approvalRequiredFor": ["brain.write", "private_context.read", "connected_tool.write", "remote_repo.write"]
+  },
+  "update": {
+    "channel": "manual",
+    "check": "youmd stack smoke",
+    "source": "user-owned GitHub repo or local stack folder",
+    "autoApply": false
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "youmd",
-  "version": "0.6.21",
+  "version": "0.6.27",
   "description": "Identity context protocol for the agent internet — an MCP where the context is you. CLI for the You.md platform.",
   "bin": {
     "you": "dist/you.js",
@@ -19,8 +19,8 @@
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest",
-    "prepublishOnly": "npm run build",
-    "postinstall": "node dist/postinstall.js"
+    "prepublishOnly": "node scripts/check-version-exists.mjs && npm run build",
+    "postinstall": "node -e \"try{require('./dist/postinstall.js')}catch(e){if(e&&e.code!=='MODULE_NOT_FOUND')throw e}\""
   },
   "keywords": [
     "identity",

package/skills/claude-md-generator.md

@@ -19,7 +19,7 @@ Generate a CLAUDE.md for the current project, pre-loaded with your identity so e
 ## What This Skill Does
 
 1. Detect project type (package.json, Cargo.toml, go.mod, pyproject.toml, etc.)
-2. Read existing CLAUDE.md or project-context/ if present
+2. Read existing CLAUDE.md and `project-context/` if present (especially `CURRENT_STATE.md`, `feature-requests-active.md`, and `TODO.md`)
 3. Generate CLAUDE.md with:
    - Your identity summary (who you are, what you're building)
    - Your agent preferences (how coding agents should behave)

package/skills/meta-improve.md

@@ -18,17 +18,22 @@ The feedback loop that makes your identity smarter over time. Agents review what
 ## What This Skill Does
 
 1. Read skill-metrics.json for usage data (which skills run, success/fail rates)
-2. Analyze patterns:
+2. Brain-aware preflight: if you are running inside a repo, skim `project-context/` first so you don’t propose generic changes the project already answered:
+   - `project-context/CURRENT_STATE.md`
+   - `project-context/feature-requests-active.md`
+   - `project-context/TODO.md`
+   - `project-context/reference-intelligence/TASKS.md`
+3. Analyze patterns:
    - Which skills get used most?
    - Which identity fields get referenced most?
    - Are there gaps? (skills that should exist but don't)
    - Are there stale entries? (skills never used)
-3. Propose changes:
+4. Propose changes:
    - New directives based on repeated corrections
    - Voice refinements based on agent interactions
    - Skill additions based on detected workflow patterns
    - Pruning of unused skills
-4. Present proposals for user approval (never auto-apply)
+5. Present proposals for user approval (never auto-apply)
 
 ## Metrics Tracked
 

package/skills/proactive-context-fill.md

@@ -23,7 +23,7 @@ Use this skill when starting a new session with a user who has a you.md identity
 1. Scan the bundle on session start (read the relevant sections)
 2. Build a list of detected gaps
 3. Present the list to the user concisely
-4. Offer YES/SKIP/ASK_LATER for each gap
+4. Offer YES/SKIP/ASK_LATER for each gap (explicit consent; never auto-fill)
 5. Execute the chosen actions in batches
 6. Allow skipping individual sub-tasks (e.g. "scaffold all projects but skip BAMF.ai")
 

package/skills/youstack-maintainer.md

@@ -0,0 +1,128 @@
+---
+name: youstack-maintainer
+description: Maintain, organize, update, and safely improve a user's YouStacks.
+version: 1.0.0
+scope: shared
+identity_fields:
+  - profile.about
+  - preferences.agent
+  - directives.agent
+  - voice.overall
+---
+
+# youstack-maintainer
+
+Use this skill when the user asks to create, organize, improve, update, share, publish, or audit YouStacks.
+
+## Core Rule
+
+You.md is the brain. YouStacks are named execution packages built on top of that brain.
+
+Keep stacks private by default. Never make a stack public, widen a scoped link, read private memory, write brain data, call connected tools, or push to a remote repo unless the user explicitly approves that exact action.
+
+## Startup
+
+1. If the You.md auto-upgrade helper exists, run it quietly before editing stack files:
+
+   ```bash
+   ~/.youmd/bin/youmd-auto-upgrade --quiet || true
+   ```
+
+2. Discover stack manifests from the current repo, `youstacks/`, `.you/youstack.json`, or the user's chosen stack folder.
+3. Run `youmd stack doctor --path <stack>`, then `youmd stack smoke --path <stack>` before trusting a manifest.
+4. Read the stack's `improvement`, `update`, `sharing`, and `accessPolicy` blocks before changing anything.
+5. Prefer local/static stack files first. Use You.md API/MCP only for protected brain retrieval, sync, tokens, grants, connected tools, hosted telemetry, or server-side actions.
+6. Brain-aware preflight: before asking the user basic repo questions, skim the current repo context if present:
+   - `project-context/CURRENT_STATE.md`
+   - `project-context/feature-requests-active.md`
+   - `project-context/TODO.md`
+   - `project-context/reference-intelligence/TASKS.md`
+7. Upstream-aware preflight: if a stack change touches shared agent rules, skills, scripts, prompts, host adapters, or distribution, check the current reference-intelligence task list for relevant GStack, GBrain, Agent Scripts, or The Library signals before designing the change.
+
+## Organize A Stack
+
+For each stack, make sure it has:
+
+- A clear human name, stable slug, domain, aliases, and tags.
+- Skills in `skills/<name>/SKILL.md`.
+- Workflows in `workflows/`.
+- Optional sub-agents in `subagents/`.
+- Examples and golden prompts in `examples/` or `prompts/`.
+- Smoke checks or eval notes in `tests/`.
+- Docs in `docs/`.
+- Host adapters for Claude Code, Codex, and Cursor.
+- Optional pointer-catalog entries for repo-owned skills, prompts, scripts, agents, and examples that should stay canonical in their source repo instead of being copied.
+- Typed dependencies between skills, sub-agents, prompts, scripts, and protected capabilities so install/use flows can pull prerequisites before the requested capability.
+- A read-only diagnostic path for manifest bloat, route ambiguity, adapter drift, update hygiene, and public-readiness gaps.
+- An improvement policy and update policy.
+- A private/public/scoped sharing policy with `private` as the default.
+
+## Improve A Stack
+
+Use safe signals first:
+
+- User corrections.
+- Failed or ambiguous route choices.
+- Smoke failures.
+- Evals and golden prompt regressions.
+- Repo diffs.
+- Repeated manual edits.
+- New docs or examples the user approves.
+- Reference-intelligence tasks that are relevant:
+  - GStack for local-first skills, host adapters, evals, QA/review/release loops, and upgrade flows.
+  - GBrain for durable memory, retrieval, sync, provenance, privacy, and startup context.
+  - Agent Scripts for canonical shared AGENTS/skills/scripts/hooks, pointer-style downstream rules, skill validation, and portable helper ergonomics.
+  - The Library for private-first catalogs, reference-based installs, typed dependencies, and cross-device/team distribution.
+
+Make the smallest useful improvement. Update skills, workflows, docs, examples, tests, and generated adapters together when the change affects more than one surface. Run `youmd stack smoke` again.
+Run `youmd stack doctor` first when a change is triggered by route misses, bloat, stale adapters, memory/resource issues, or a reference-intelligence task.
+
+## Source Of Truth Rules
+
+- Prefer pointers over copies when a skill, prompt, script, or agent is owned by another repo and should improve there first.
+- Use managed blocks or generated adapter files for downstream repos; preserve repo-local rules below the managed pointer.
+- Keep helper scripts dependency-light and portable unless the manifest explicitly declares the runtime.
+- Validate skill front matter after edits and before commit or publish.
+- Never install public internet skills into a private stack without owner review.
+- Pull dependencies first when a stack capability declares `skill:*`, `agent:*`, `prompt:*`, `script:*`, or `protected:*` requirements.
+
+## Visibility
+
+- `private`: default. Visible only to the owner and local agents with file access.
+- `scoped-link`: share a bounded install/grant with a teammate, friend, or contractor.
+- `team`: shared within an approved workspace/team.
+- `public-open`: inspectable, forkable, installable public stack. Strip secrets, private memories, proprietary prompts, private examples, and internal tool details first.
+
+When the user says "make this stack public", first prepare a public-readiness diff:
+
+1. Confirm the stack name and slug.
+2. List files that will become public.
+3. List protected capabilities that remain behind You.md auth.
+4. Remove or redact secrets, private memories, private context, private links, and proprietary prompts.
+5. Run smoke checks.
+6. Ask for final approval before publishing or pushing.
+
+## BAMFStack Lighthouse Pattern
+
+BAMFStack is the reference proof for an open YouStack:
+
+- One curl install.
+- Host-native skills and commands.
+- Local helper CLI.
+- Env-only API key handling.
+- Auto-upgrade preamble.
+- Capability discovery.
+- Deterministic workflow routing.
+- Read-only smoke test.
+- Read-only stack doctor/diagnostic pass.
+- Docs-quality examples.
+- Sync rule: update stack files, docs, API/MCP references, prompts, and tests together.
+
+Copy the pattern, not the private implementation. Keep proprietary prompts, product internals, credentials, private creator data, and sensitive actions behind authenticated BAMF or You.md API/MCP surfaces.
+
+## External Inspiration Map
+
+- GStack: product feel for installable agent operating systems.
+- GBrain: product feel for a durable shared brain across agents.
+- Agent Scripts: product feel for canonical shared rules, skills, scripts, hooks, and repo-owned skill symlinks that stay simple enough to maintain.
+- The Library: product feel for a private-first catalog where agentic assets are referenced, pulled on demand, synced, and shared without forcing everything into a public marketplace.

package/skills/youstack-start.md

@@ -0,0 +1,78 @@
+---
+name: youstack-start
+version: 1.0.0
+scope: shared
+identity_fields: [profile.about, preferences.agent, directives.agent, voice.overall]
+description: Start a local Claude/Codex/Cursor session with the user's identity, project state, active requests, installed skills, and next move.
+---
+
+# youstack-start
+
+Use this skill at the beginning of a local-agent session, or when the user says "continue", "what should we do next", "use you.md", "use youstack", or asks you to make an existing repo smarter for agents.
+
+YouStack is the you.md operating layer for local agents: identity, project context, skills, scripts, prompts, sub-agents, memory, activity logs, and safe additive repo bootstrapping.
+
+## Identity Context
+
+- **About:** {{profile.about}}
+- **Agent preferences:** {{preferences.agent}}
+- **Directives:** {{directives.agent}}
+- **Voice:** {{voice.overall}}
+
+## First Calls
+
+If the You.md MCP server is available, call these in order:
+
+1. `whoami`
+2. `get_agent_brief` with `format: "markdown"`
+3. `list_skills`
+4. `use_skill` with `name: "youstack-start"` if the skill has not already been loaded
+
+If MCP is not available but the CLI is installed, use:
+
+```bash
+youmd whoami
+youmd skill list
+youmd skill use youstack-start
+```
+
+If neither is available, read the repo's normal instruction files first: `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/`, `.you/`, and `project-context/`.
+
+## Operating Loop
+
+1. Read the entire user request and extract every actionable request.
+2. Read local project instructions before designing or editing.
+3. Check `project-context/feature-requests-active.md`, `project-context/CURRENT_STATE.md`, and `project-context/TODO.md` when present.
+4. Pick the highest-value next move from real context, not a generic command list.
+5. Act end-to-end: implement, verify, update trackers, and report what actually changed.
+6. Prefer additive changes to generated agent layers (`.you/`, `.claude/skills/youmd/`, `.codex/skills/youmd/`) before rewriting mature human-owned docs.
+7. When a repo already has canonical shared rules or skills elsewhere, add a pointer/managed block instead of duplicating the full text.
+
+## Skill Routing
+
+Use the available You.md skills as follows:
+
+- `project-context-init` when a repo lacks a usable project-context spine.
+- `claude-md-generator` when a host-specific agent entrypoint is missing or stale.
+- `voice-sync` after voice or communication preferences change.
+- `proactive-context-fill` when identity or project context is thin.
+- `you-logs` when the user wants proof of which agents accessed context.
+- `meta-improve` after repeated sessions to convert corrections into better identity or skill instructions.
+- `youstack-maintainer` when a repo needs shared skills, scripts, prompts, sub-agents, source pointers, host adapters, or stack sync improved.
+
+## Guardrails
+
+- Do not ask the user to paste files you can read locally.
+- Do not claim You.md pushed, published, linked, or wrote anything unless the tool or command actually succeeded.
+- Do not overwrite existing `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, or project-context files wholesale. Merge or add a managed block.
+- Do not copy repo-owned skills/prompts/scripts into a stack when a source pointer would keep the upstream repo canonical.
+- Do not stop at "here is a plan" when the user asked you to continue improving the stack.
+- Save durable learnings as memories or project notes when the host supports it.
+
+## Done Means
+
+- The current request is tracked.
+- The relevant code, skill, MCP, API, or docs surface is actually updated.
+- The change is tested with the smallest meaningful local verification.
+- Project trackers reflect the state honestly.
+- The final response names what changed and what still needs production/user verification.