{"id":51155636,"url":"https://github.com/rishabhsai/intentfile","last_synced_at":"2026-06-26T10:02:05.518Z","repository":{"id":358089530,"uuid":"1239978391","full_name":"rishabhsai/intentfile","owner":"rishabhsai","description":"A tiny open format for agent task contracts, acceptance criteria, and proof-of-done.","archived":false,"fork":false,"pushed_at":"2026-05-16T17:53:04.000Z","size":22224,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T14:40:17.740Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://intentfile-site.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rishabhsai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-15T16:33:55.000Z","updated_at":"2026-05-16T17:53:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rishabhsai/intentfile","commit_stats":null,"previous_names":["rishabhsai/intentfile"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/rishabhsai/intentfile","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhsai%2Fintentfile","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhsai%2Fintentfile/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhsai%2Fintentfile/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhsai%2Fintentfile/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rishabhsai","download_url":"https://codeload.github.com/rishabhsai/intentfile/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rishabhsai%2Fintentfile/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34811922,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-26T02:00:06.560Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-26T10:02:04.657Z","updated_at":"2026-06-26T10:02:05.511Z","avatar_url":"https://github.com/rishabhsai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# intentfile\n\nStop giving agents vague prompts.\n\n`intentfile` is a tiny open format for agent tasks. It defines the objective,\nconstraints, permissions, acceptance criteria, and proof required before an\nagent can call the job done.\n\n```yaml\nintent: intentfile/v0.1\nid: intent_01J7W7M2ZK7QH6Z7N9Z6M1A4X8\ntitle: Add password reset flow\nobjective: Implement an email-based password reset flow for existing users.\n\nacceptance:\n  - id: A1\n    statement: Users can request a password reset link by email.\n  - id: A2\n    command: npm test\n    must_pass: true\n\nproof_required:\n  - changed_files\n  - tests_run\n  - acceptance_checklist\n```\n\n## Why this exists\n\nAI coding agents can do useful work, but the handoff format is still weak. A\nchat prompt, issue comment, or loose Markdown checklist is easy to misread and\nhard to audit later.\n\nAn `.intent.yaml` file is a portable task contract:\n\n- what the agent should do\n- what context it should consider\n- what files, tools, and domains it may use\n- what \"done\" means\n- what proof must come back\n\nThe project is intentionally small. It should compose with Codex, Claude Code,\nCursor, GitHub Actions, MCP, A2A, custom runners, and normal human review.\n\n## Quick start\n\n```bash\nnpm install\nnpm run build\nnpm run intent -- init \"Add password reset flow\" --out task.intent.yaml\nnpm run intent -- validate task.intent.yaml\nnpm run intent -- brief task.intent.yaml --target codex\nnpm run intent -- goal task.intent.yaml --target codex\nnpm run intent -- proof task.intent.yaml --out task.proof.yaml\nnpm run intent -- verify task.intent.yaml task.proof.yaml\n```\n\nThe CLI binary is named `intent` once the package is installed globally or run\nfrom the built workspace.\n\n```bash\nintent init \"Fix checkout bug\" --template bugfix --out checkout.intent.yaml\nintent validate checkout.intent.yaml\nintent brief checkout.intent.yaml --target codex\nintent goal checkout.intent.yaml --target codex\n```\n\n## Codex `/goal`\n\nCodex `/goal` keeps Codex working toward a durable objective. `intentfile`\ndefines what done means for that objective.\n\n```txt\n/goal keeps Codex moving. intentfile defines done.\n```\n\nRender a copyable goal command:\n\n```bash\nnpm run intent -- goal task.intent.yaml --target codex\n```\n\nFor longer tasks, render a goal document and point Codex at it:\n\n```bash\nnpm run intent -- goal task.intent.yaml --target codex --format markdown --out task.goal.md\n```\n\nThen paste:\n\n```txt\n/goal follow the instructions in task.goal.md\n```\n\nSee [docs/CODEX_GOAL.md](./docs/CODEX_GOAL.md) for the full workflow.\n\n## Demo video\n\nWatch the launch demo: [demos/intentfile-goal-demo.mp4](./demos/intentfile-goal-demo.mp4)\n\n![intentfile video poster](./demos/intentfile-goal-demo-poster.png)\n\nThe editable Remotion source lives in `apps/video`. Re-render it with:\n\n```bash\nnpm run render:video\n```\n\nSee [docs/VIDEO_DEMO.md](./docs/VIDEO_DEMO.md) for the storyboard and editing\nnotes.\n\n## Copy-paste prompt for your agent\n\nPaste this into a coding agent when you want it to install intentfile, load the\nrepo skill, verify the CLI, and start working from an `.intent.yaml` contract:\n\n```txt\nInstall and use intentfile in this workspace.\n\nRepository: https://github.com/rishabhsai/intentfile\n\nTasks:\n1. Clone the repo if it is not already present, then run npm install, npm run build, npm test, npm run typecheck, and npm audit.\n2. Use the CLI through npm run intent -- from the repo. If global npm links are acceptable in this environment, run npm link -w packages/cli and verify intent --help.\n3. If Codex-style local skills are supported, install the repo skill by copying skills/intentfile to ${CODEX_HOME:-$HOME/.codex}/skills/intentfile. If local skills are not supported, read skills/intentfile/SKILL.md and follow it as your operating guide.\n4. Read AGENTS.md, docs/AGENT_ONBOARDING.md, docs/CODEX_GOAL.md, spec/intentfile-v0.1.md, and examples/password-reset.intent.yaml.\n5. Create or update a .intent.yaml for the task I give you, validate it, render a brief for the target agent, and if Codex /goal is available render a goal with npm run intent -- goal task.intent.yaml --target codex.\n6. Treat the intent objective, constraints, acceptance, and proof_required as the definition of done. Require a .proof.yaml before calling the work done.\n7. At the end, report the exact commands you ran, changed files, acceptance status, and any unresolved questions.\n```\n\nFor a slower, more explicit version of this workflow, see\n[docs/AGENT_ONBOARDING.md](./docs/AGENT_ONBOARDING.md).\n\n## Repository layout\n\n```txt\nintentfile/\n  README.md\n  AGENTS.md\n  spec/\n    intentfile-v0.1.md\n    intentfile.schema.json\n    proof.schema.json\n  examples/\n    password-reset.intent.yaml\n    codex-goal.intent.yaml\n    dependency-upgrade.intent.yaml\n    bugfix.intent.yaml\n    research.intent.yaml\n    proof/password-reset.proof.yaml\n  packages/\n    core/\n    cli/\n  apps/\n    site/\n    video/\n  docs/\n    AI_AGENT_SETUP.md\n    AGENT_ONBOARDING.md\n    CODEX_GOAL.md\n    COPY_PASTE_AGENT_PROMPT.md\n    ROADMAP.md\n    VIDEO_DEMO.md\n  skills/\n    intentfile/\n  demos/\n    codex/\n    github-action/\n    intentfile-goal-demo.mp4\n    intentfile-goal-demo-poster.png\n```\n\n## Current implementation\n\n- `@intentfile/core`: TypeScript parser, schema validation, brief rendering,\n  starter proof generation, and proof verification.\n- `@intentfile/cli`: `intent init`, `validate`, `brief`, `goal`, `proof`,\n  `verify`, `convert`, and `from github`.\n- `apps/site`: simple editorial website using the same sparse rhythm as\n  `new.rishabhsai.com`.\n- `apps/video`: Remotion source for the short Codex `/goal` launch video.\n- `.github/workflows/test.yml`: install, test, typecheck, and build.\n\nThis is v0.1 groundwork. The verifier is conservative by design: it can check\nschemas, required proof fields, acceptance status, obvious path boundaries, and\ncommand results when asked to run them. It does not pretend to prove product\nsemantics without domain-specific tests.\n\n## For AI agents\n\nStart with [AGENTS.md](./AGENTS.md), then follow\n[docs/AGENT_ONBOARDING.md](./docs/AGENT_ONBOARDING.md). If your agent supports\nCodex-style local skills, install or read [skills/intentfile/SKILL.md](./skills/intentfile/SKILL.md).\nThe docs are written for fresh agents that need to clone, install, verify, and\nsafely continue work.\n\n## Status\n\nThis repository is ready for early spec discussion and CLI iteration. The next\nuseful milestones are stricter path matching, GitHub Action packaging, signed\nproof experiments, and richer examples for real agent workflows.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabhsai%2Fintentfile","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frishabhsai%2Fintentfile","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frishabhsai%2Fintentfile/lists"}