{"id":50486794,"url":"https://github.com/yazilim-vip/nova-workspace","last_synced_at":"2026-06-01T23:02:25.272Z","repository":{"id":352618458,"uuid":"1215718393","full_name":"yazilim-vip/nova-workspace","owner":"yazilim-vip","description":"Workspace engineering intelligence — an AGENTS.md-based framework for agent-driven development","archived":false,"fork":false,"pushed_at":"2026-04-27T12:54:40.000Z","size":315,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T14:06:05.643Z","etag":null,"topics":["agents-md","ai-agents","claude-code","developer-tools","nova","workspace"],"latest_commit_sha":null,"homepage":"","language":"Go Template","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/yazilim-vip.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":null,"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-04-20T07:29:32.000Z","updated_at":"2026-04-27T12:54:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/yazilim-vip/nova-workspace","commit_stats":null,"previous_names":["yazilim-vip/nova-workspace"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/yazilim-vip/nova-workspace","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazilim-vip%2Fnova-workspace","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazilim-vip%2Fnova-workspace/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazilim-vip%2Fnova-workspace/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazilim-vip%2Fnova-workspace/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yazilim-vip","download_url":"https://codeload.github.com/yazilim-vip/nova-workspace/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yazilim-vip%2Fnova-workspace/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33797128,"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-01T02:00:06.963Z","response_time":115,"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":["agents-md","ai-agents","claude-code","developer-tools","nova","workspace"],"created_at":"2026-06-01T23:02:24.355Z","updated_at":"2026-06-01T23:02:25.266Z","avatar_url":"https://github.com/yazilim-vip.png","language":"Go Template","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NOVA — Workspace Engineering Intelligence\n\nA minimal, opinionless framework for running AI agents across multi-repo development workspaces. Originated and maintained by the [yazilim.vip](https://yazilim.vip) crew; shipped for anyone who wants it.\n\nNOVA is a markdown-based framework built on the [AGENTS.md](https://agents.md) convention. It gives an AI agent a consistent identity, safety rules, and navigation protocol across a multi-repo workspace — so the agent behaves the same way whether you're in Claude Code, Cursor, Codex, or any other AGENTS.md-compatible tool.\n\n**NOVA ships its own machinery, not opinions about your code.** The framework brings workspace onboarding, deliberate upstream sync, per-platform adapter wiring, and a project-structure convention. It stays out of how you write code, use git, run Kubernetes, or manage infrastructure — those choices live with you, in the tier that fits.\n\n## What you get\n\n- **`AGENTS.md`** — the agent's identity, safety rules, and navigation protocol.\n- **`SOUL.md`** — voice and depth, loaded only when the task demands it.\n- **`.ai/enforcement.md`** — platform-agnostic contract that turns prose rules into deterministic agent behavior (session-start broadcast, per-turn re-injection, scoped activation, optional pre-edit gate, focused subagent).\n- **`.ai/procedures/adapters/`** — per-platform implementations of the enforcement contract. Ships [Claude Code](.ai/procedures/adapters/claude/README.md) and [Kiro](.ai/procedures/adapters/kiro/README.md) today; pluggable for more.\n- **Framework procedures under `.ai/procedures/\u003cname\u003e/PROCEDURE.md`** — workspace-bound multi-step workflows. NOT [agentskills.io](https://agentskills.io)-conformant — they reference workspace paths (`AGENTS.md`, `.ai/workspace/`, `.claude/`, `.kiro/`) by absolute path because their job IS to operate on those paths. Listed in `AGENTS.md` § \"Framework Procedures\"; loaded on trigger:\n  - `onboarding` — guided workspace setup.\n  - `self-update` — deliberate upstream sync.\n  - `adapters` — generate per-platform steering, hooks, subagents.\n  - `ide` — editor setup. IntelliJ multi-module project; Neovim with `claudecode.nvim` MCP bridge.\n  - `terminal` — terminal multiplexer (tmux) and host-emulator settings Claude requires.\n  - `dream` — periodic memory consolidation pass over learnings + drift log.\n  - `personal-knowledge-management` — manages a personal knowledge vault under `notes/`.\n- **`.ai/project-structure.md`** — NOVA's convention for a single project's AGENTS.md / `.ai/` layout. A reference doc.\n- **`.ai/workspace/`** — the local workspace instance (gitignored; populated during onboarding) — workspace identity, repo map, infra config, accumulated learnings.\n- **`git-repositories/`** — the clone convention (`\u003cplatform\u003e/\u003cgroup\u003e/\u003crepo\u003e`; gitignored).\n\n**Mental model:**\n- `.ai/procedures/\u003cname\u003e/PROCEDURE.md` = NOVA's own framework procedures (workspace-bound workflows, listed in AGENTS.md table). Not portable agentskills.io skills.\n- `.ai/*.md` = NOVA's conventions (read when context demands).\n- `.ai/procedures/adapters/` = per-platform pointers + hooks + subagents (committed; runtime outputs like `.claude/`, `.kiro/` are gitignored, regenerable).\n- `.ai/workspace/` = your local workspace state (gitignored). Identity overrides, repo map, infra config, learnings.\n\nNOVA never writes into `.ai/workspace/` upstream — your local state stays yours.\n\n## Why workspace-level, not repo-level?\n\nMost agent tooling operates inside a single repo. Real engineering work spans many repos — apps, infra, shared libraries, docs. NOVA sits one level above: it's the thing that tells the agent *which* repo to enter, what conventions it uses, and where your tooling lives.\n\n## Why prose plus enforcement?\n\nLLM compliance with prose rules is probabilistic, and attention to mid-context instructions decays as the conversation grows. NOVA's `AGENTS.md` is the prose; `.ai/procedures/adapters/` is what makes it stick:\n\n- **Session-start broadcast** — workspace identity + nav protocol injected at position 0 (Claude `@`-imports, Kiro `inclusion: always` steering).\n- **Per-turn re-injection** — a 5-line checklist re-injected on every user prompt via platform hooks, refreshing attention at the end of context where it's strongest.\n- **Scoped activation** — entering `git-repositories/\u003crepo\u003e/` auto-loads that repo's `AGENTS.md` (Kiro `fileMatch`; on Claude, delegated to the `repo-worker` subagent).\n- **Optional pre-edit gate** — `fs_write` under a repo blocks until that repo's `AGENTS.md` was read this session (Kiro `preToolUse` hook; opt-in).\n- **Focused subagents** — `repo-worker` and `dream-worker` ship as fresh-context archetypes with the rulebook pre-walked at definition time.\n\nThe full contract lives at [.ai/enforcement.md](.ai/enforcement.md). Adapters are pointers, never copies — every rule still has one source of truth.\n\n## Getting started\n\n1. Clone this repo into a new workspace directory.\n2. Open the workspace in your agent (Claude Code, Kiro, Cursor, Codex, etc.).\n3. Say **\"set up my workspace\"** — NOVA will guide you through onboarding.\n4. Say **\"set up the \\\u003cplatform\u003e adapter\"** to generate platform-native steering, hooks, and subagents (`.claude/`, `.kiro/`).\n5. (Optional) Clone your project repos into `git-repositories/` following the `\u003cplatform\u003e/\u003cgroup\u003e/\u003crepo\u003e` convention.\n\nManual alternative: copy `.ai/procedures/onboarding/assets/map/repos.md` → `.ai/workspace/map/repos.md` and `.ai/procedures/onboarding/assets/infra.md` → `.ai/workspace/infra.md`, then fill them in yourself.\n\n## What onboarding looks like\n\nNOVA uses a guided conversation — it asks 2-3 questions at a time, adapts to your answers, and generates the workspace instance files at the end.\n\nSee a full example conversation in [.ai/procedures/onboarding/assets/example-dialogue.md](.ai/procedures/onboarding/assets/example-dialogue.md) — identity → repos → infra → rules → AI tool → generated-files preview, plus short variants for skipping a topic, adding a repo later, and the first post-onboarding task.\n\n## Bringing your own skills\n\nSkills are portable, self-contained capabilities in [agentskills.io](https://agentskills.io) format — `SKILL.md` with `name` + `description` frontmatter, optional `scripts/` `references/` `assets/` subfolders, references via paths relative to the skill root. Skills can live at any tier of the workspace; NOVA prescribes no location.\n\n- **Workspace user skills** — generic, cross-repo skills you write yourself. Common spots: host-native location (e.g. `.claude/skills/` for Claude Code, picked up by the native loader), `.ai/workspace/skills/`, or wherever else suits you. Each platform's adapter at `.ai/procedures/adapters/\u003cplatform\u003e/README.md` § \"Skills\" describes the native path.\n- **Project skills** — domain-specific skills owned by one repo. Declared in the repo's own `AGENTS.md` and stored at the repo's choice (`\u003crepo\u003e/.ai/skills/\u003cname\u003e/SKILL.md` is one common convention, not required). Auto-loaded when the agent enters the repo.\n\nPick whichever tier(s) fit your workflow. Mix freely. See `AGENTS.md` § \"Skills\" and `.ai/project-structure.md` § \"Project Skills\" for details.\n\n\u003e NOVA's framework procedures (`.ai/procedures/`) are NOT skills. They're workspace-bound workflows that happen to use SKILL-style frontmatter for discovery — see § \"Framework Procedures\" in AGENTS.md.\n\n**Sharing user skills across a team is a fork-level decision, not a framework one.** Common patterns: commit at the chosen path, keep team skills in a separate repo and symlink, or any other convention that fits.\n\nExample skill frontmatter:\n\n```markdown\n---\nname: my-skill\ndescription: One-line description of what this skill does and when to use it.\nmetadata:\n  author: your-name\n  version: \"0.1.0\"\n---\n```\n\n## Staying current with upstream\n\nIf you've forked NOVA, sync deliberately — don't blind-merge:\n\n```bash\ngit remote add upstream https://github.com/yazilim-vip/nova-workspace.git\n```\n\nThen ask your agent to \"sync with upstream\". It'll follow the flow in [.ai/procedures/self-update/PROCEDURE.md](.ai/procedures/self-update/PROCEDURE.md): fetch, classify each change, surface conflicts, apply or skip with reasons recorded.\n\n## Contributing upstream\n\nIf you've built framework-level improvement — a better onboarding question, a fix to the self-update flow, a clearer convention — open a PR. Keep it focused: framework changes, not opinions. By contributing, you agree to the MIT License.\n\n## Status\n\nEarly. Minimal on purpose. Shipped as *how our crew runs its agent workflow*, not as a polished product. Take what's useful, fork it, adapt it.\n\n## License\n\n[MIT](./LICENSE) © yazilim.vip\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyazilim-vip%2Fnova-workspace","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyazilim-vip%2Fnova-workspace","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyazilim-vip%2Fnova-workspace/lists"}