@minhpnq1807/contextos 0.5.53 → 0.6.1

package/community-skills/redis/skill.yaml

@@ -0,0 +1,22 @@
+id: redis
+name: Redis
+description: Add and debug Redis cache, TTL, sessions, rate limits, queues, and pub/sub behavior.
+positive_triggers:
+  prompts: [redis, cache, caching, ttl, session, rate limit, queue, bullmq, invalidation]
+  files: [redis.conf, docker-compose.yml]
+  dependencies: [redis, ioredis, bullmq, cache-manager-redis-store]
+evidence:
+  files: [redis.conf, docker-compose.yml, docker-compose.yaml]
+  dependencies: [redis, ioredis, bullmq, cache-manager, cache-manager-redis-store]
+negative_triggers:
+  prompts: [browser cache, next cache, static cache]
+  dependencies: [swr]
+workflow:
+  - Inspect client setup, cache keys, TTLs, and invalidation paths.
+  - Identify whether Redis backs cache, queue, session, rate limit, or pub/sub behavior.
+  - Patch the smallest service boundary while preserving key conventions.
+  - Verify with focused tests or a command that exercises the Redis path.
+related_skills:
+  - performance-optimization
+  - backend-development
+  - observability

package/community-skills/vercel/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: Vercel Deployment
+description: Fix Next.js and Vercel deployment failures, environment issues, build output problems, and production routing regressions.
+---
+
+# Vercel Deployment
+
+Use this skill when the repo has Vercel or Next.js evidence such as `vercel.json`, `next`, or `next.config.*`.
+
+## Workflow
+
+1. Inspect `vercel.json`, Next config, package scripts, and deployment logs.
+2. Check build command, output directory, environment variables, and route/runtime settings.
+3. Patch the minimal config or code path that explains the deployment failure.
+4. Verify with the project build command and any available Vercel validation.

package/community-skills/vercel/skill.yaml

@@ -0,0 +1,22 @@
+id: vercel
+name: Vercel Deployment
+description: Fix Vercel and Next.js deployment failures.
+positive_triggers:
+  prompts: [vercel, deployed, deploy, production, preview, build failed, environment variable]
+  files: [vercel.json, next.config.js, next.config.ts]
+  dependencies: [next, vercel]
+evidence:
+  files: [vercel.json, next.config.js, next.config.ts, .github/workflows/*]
+  dependencies: [next, vercel, react]
+negative_triggers:
+  dependencies: [expo, react-native, eas-cli]
+  files: [eas.json, app.json]
+workflow:
+  - Inspect Vercel config, Next config, package scripts, and deploy logs.
+  - Check build command, output directory, env vars, runtime, and route config.
+  - Patch the minimal config or code path that explains the failure.
+  - Verify with the project build command.
+related_skills:
+  - github-actions-ci-cd
+  - env-secret-management
+  - build-log-debugging

package/docs/demo/agents-lost-middle.txt

@@ -0,0 +1,28 @@
+$ cat AGENTS.md
+1. General style
+2. Formatting
+3. Test names
+...
+37. IMPORTANT: Always use code-review-graph before grep.
+...
+52. Release notes
+
+$ codex "fix failing test"
+Raw agent starts with grep
+Rule followed: no
+
+$ ctx debug -- "fix failing test"
+ContextOS debug
+Critical ContextOS rules:
+- IMPORTANT: Always use code-review-graph before grep.
+
+Suggested files to check:
+- test/score-context.test.js
+- plugins/ctx/lib/score-context.js
+
+$ codex + ContextOS
+Rule followed: yes
+Evidence: graph checked before file reads
+
+AGENTS.md did not change.
+The rule moved from buried context into runtime context.

package/docs/demo/contextos-ready.txt

@@ -0,0 +1,20 @@
+$ ctx doctor
+Repository Score
+
+Rules: 100
+Skills: 100
+Workflows: 100
+
+Overall:
+ContextOS Ready Gold
+
+Evidence:
+- Rules: 1 AGENTS.md source(s), 5 actionable rule(s)
+- Skills: 3 skill(s), 3 metadata file(s)
+- Workflows: 2 workflow(s), 2 with agent chain(s)
+
+$ badge
+[ContextOS Ready Gold]
+
+Repos now have a target:
+AGENTS.md + skills + workflows + evidence.

package/docs/demo/same-prompt-different-context.txt

@@ -0,0 +1,26 @@
+$ ctx leaderboard --hallucination
+Hallucination Leaderboard
+Repos: 12
+Tasks: 20
+
+System              Correct Skill
+------------------  -------------
+Raw Agent           10.0%
+ContextOS + Codex   80.0%
+
+$ ctx skills doctor -- "fix deployed"  # Expo repo
+ContextOS skill doctor
+1. eas high confidence
+   evidence: eas.json, app.json, expo dependency
+2. mobile-deployment high confidence
+3. github-actions-ci-cd medium confidence
+
+$ ctx skills doctor -- "fix deployed"  # Next.js repo
+ContextOS skill doctor
+1. vercel-deployment high confidence
+   evidence: vercel.json, next dependency
+2. github-actions-ci-cd high confidence
+3. env-secret-management medium confidence
+
+Same prompt. Same model. Different repo evidence.
+ContextOS routes the right skill before the agent edits code.

package/docs/launch-demos.md

@@ -0,0 +1,127 @@
+# Launch Demos
+
+These are demo scripts for explaining ContextOS quickly. They are intentionally small and visual.
+
+## 1. Agent Hallucination Benchmark
+
+GIF: [`docs/demo/same-prompt-different-context.gif`](demo/same-prompt-different-context.gif)
+
+Prompt:
+
+```text
+Fix deployment
+```
+
+Raw agent:
+
+```text
+Suggests: Vercel, Docker, Railway
+Reason: guessed from common deployment tools
+```
+
+ContextOS:
+
+```text
+Detected:
+- eas.json
+- expo dependency
+- GitHub workflow
+
+Selected:
+- eas
+- mobile-deployment
+- github-actions-ci-cd
+```
+
+Message:
+
+```text
+Same prompt. Same model. Different context.
+```
+
+## 2. AGENTS.md Lost In The Middle
+
+GIF: [`docs/demo/agents-lost-middle.gif`](demo/agents-lost-middle.gif)
+
+Setup:
+
+```text
+AGENTS.md
+  rule 1
+  rule 2
+  ...
+  IMPORTANT: Always use code-review-graph before grep.
+  ...
+  rule 40
+```
+
+Raw agent:
+
+```text
+Misses the buried rule.
+```
+
+ContextOS:
+
+```text
+Extracts the relevant rule and injects it before work starts.
+```
+
+Message:
+
+```text
+Important repo rules should not depend on where they appear in a long file.
+```
+
+## 3. Repo-Aware Skills
+
+GIF: [`docs/demo/same-prompt-different-context.gif`](demo/same-prompt-different-context.gif)
+
+Prompt:
+
+```text
+fix deployed
+```
+
+Repo A:
+
+```text
+Evidence: expo, eas.json
+Skills: eas, mobile-deployment
+```
+
+Repo B:
+
+```text
+Evidence: next, vercel.json
+Skills: vercel-deployment, github-actions-ci-cd
+```
+
+Repo C:
+
+```text
+Evidence: Dockerfile, docker-compose.yml
+Skills: docker, build-log-debugging
+```
+
+Message:
+
+```text
+Context is not extra text. It changes the correct answer.
+```
+
+## 4. ContextOS Ready
+
+GIF: [`docs/demo/contextos-ready.gif`](demo/contextos-ready.gif)
+
+Command:
+
+```bash
+ctx doctor
+```
+
+Message:
+
+```text
+Repos now have a target: AGENTS.md + skills + workflows + evidence.
+```

package/docs/roadmap.md

@@ -0,0 +1,285 @@
+# Roadmap
+
+ContextOS is past the core routing layer. The next work should make the value visible faster and create a community loop.
+
+## P1: Hallucination Leaderboard
+
+The strongest launch artifact is not another feature. It is a leaderboard that shows raw prompt-only agents making plausible guesses while ContextOS routes from repo evidence.
+
+Layout:
+
+```text
+benchmarks/
+  codex/
+  claude-code/
+  cursor/
+  gemini-cli/
+  contextos/
+```
+
+Protocol:
+
+```text
+same repo
+same task
+same model when possible
+same scoring rubric
+```
+
+Example task:
+
+```text
+Task: Fix deployment
+Repo: Expo app
+```
+
+Example result:
+
+```text
+System             Correct Skill
+Raw Agent          ❌
+ContextOS + Codex  ✅
+```
+
+Target public table:
+
+```text
+Hallucination Benchmark
+
+Claude Code:        61%
+Cursor:             58%
+Raw Codex:          63%
+ContextOS + Codex:  89%
+```
+
+Why it matters:
+
+- It is easy to understand in seconds.
+- It turns ContextOS from infrastructure into a visible correctness story.
+- It creates content for GitHub, Hacker News, Reddit, and X/Twitter.
+
+## P2: Agent Replay
+
+ContextOS already records prompt context, suggested files, suggested skills, rule outcomes, telemetry, and reports. Agent Replay should turn that into a compact post-task narrative.
+
+Planned command:
+
+```bash
+ctx replay
+```
+
+Target output:
+
+```text
+Prompt:
+Fix deployment
+
+Selected skills:
+- eas
+- github-actions-ci-cd
+
+Rules followed:
+✓ Use graph first
+
+Files suggested:
+✓ eas.json
+✓ workflow.yml
+
+Files actually touched:
+✓ eas.json
+✓ workflow.yml
+
+Efficiency:
+94%
+```
+
+Why it matters:
+
+- It proves whether the injected context helped.
+- It turns local telemetry into a readable artifact.
+- It gives maintainers a quick way to debug agent behavior after the fact.
+- It is easier to demo than raw JSON reports.
+
+Likely inputs:
+
+- `last-prompt-context.json`
+- `last-report.json`
+- `prompt-history.jsonl`
+- `report-history.jsonl`
+- `telemetry.jsonl`
+- current git diff/status for touched files
+
+Non-goals for the first version:
+
+- Cloud sync
+- Dashboard
+- Cross-user analytics
+- Long-term hosted memory
+
+## P3: Community Skill Packs
+
+Do not build a full Hub first. Start with the local `community-skills/` folder that accepts PRs.
+
+Initial packs:
+
+```text
+community-skills/
+  eas/
+  vercel/
+  prisma/
+  redis/
+  oauth-google/
+  jwt-auth/
+```
+
+The seed packs now live in [`community-skills/`](../community-skills/). Each pack contains:
+
+```text
+SKILL.md
+skill.yaml
+```
+
+The Skill Router becomes more valuable when skill packs are ContextOS-ready instead of plain markdown folders.
+
+ContextOS-ready skill packs should include:
+
+```yaml
+id: oauth-google
+name: Google OAuth
+positive_triggers:
+  prompts: [oauth, google login, google sign in, callback]
+  files: [app/api/auth/*, auth.config.ts]
+  dependencies: [next-auth, "@auth/core"]
+evidence:
+  files: [app/api/auth/*, auth.config.ts, .env.example]
+  dependencies: [next-auth, "@auth/core"]
+negative_triggers:
+  prompts: [jwt only, password login]
+  dependencies: [jsonwebtoken]
+workflow:
+  - Inspect auth provider config, callback URLs, scopes, secrets, and session creation.
+  - Verify frontend login entrypoints and backend callback routes agree.
+  - Patch the smallest auth boundary while preserving session conventions.
+  - Verify with focused auth tests, typecheck, or local callback flow.
+```
+
+Possible future install flow:
+
+```bash
+ctx skills install oauth-google
+```
+
+or package-based:
+
+```bash
+npm install skill-oauth-google
+ctx sync --skills
+```
+
+Why it matters:
+
+- It creates a network effect around reusable agent capabilities.
+- It gives skill authors a structured contract: triggers, evidence, negative gates, workflow.
+- It lets ContextOS route capabilities by project evidence instead of popularity or keyword overlap.
+
+Non-goals for the first version:
+
+- Full marketplace UI
+- Paid skill hosting
+- Cloud account system
+- Remote vector database
+
+## P4: ContextOS Ready
+
+Certification can help the ecosystem self-organize without a hosted service.
+
+```text
+ContextOS Ready
+```
+
+Repository requirements:
+
+```text
+AGENTS.md
+skills/
+workflows/
+```
+
+Command:
+
+```bash
+ctx doctor
+```
+
+Target output:
+
+```text
+Repository Score
+
+Rules: 92
+Skills: 88
+Workflows: 84
+
+Overall:
+ContextOS Ready Gold
+```
+
+Why it matters:
+
+- It gives projects a concrete target.
+- It creates a badge people can add to README files.
+- It encourages community contributions without requiring a cloud product.
+
+MVP scope:
+
+- Local-only scoring.
+- No hosted account.
+- No external leaderboard dependency.
+- Rules score from project `AGENTS.md`.
+- Skills score from project skill packs with `SKILL.md` and `skill.yaml`.
+- Workflows score from project workflow markdown with agent handoff chains.
+
+## P5: Auto Skill Extraction
+
+Today, humans write `skill.yaml`. The research direction is to let ContextOS propose skill packs from repository evidence.
+
+Possible command:
+
+```bash
+ctx skill generate
+```
+
+Input:
+
+```text
+repo
+```
+
+Output:
+
+```text
+Detected Skill:
+nestjs-module
+```
+
+Target generated pack:
+
+```text
+.codex/skills/nestjs-module/
+  SKILL.md
+  skill.yaml
+```
+
+Research shape:
+
+- Detect repeated project capabilities from dependencies, config files, route/controller names, tests, and recent git activity.
+- Generate `positive_triggers`, `evidence`, `negative_triggers`, and `workflow`.
+- Mark generated packs as drafts until reviewed.
+- Let an agent or maintainer publish a cleaned-up pack into `community-skills/`.
+
+Guardrails:
+
+- Do not auto-publish generated skills.
+- Do not infer high confidence from dependency names alone.
+- Prefer explainable evidence over opaque model output.
+- Keep generated workflows short and editable.