https://github.com/yazilim-vip/nova-workspace
Workspace engineering intelligence — an AGENTS.md-based framework for agent-driven development
https://github.com/yazilim-vip/nova-workspace
agents-md ai-agents claude-code developer-tools nova workspace
Last synced: 22 days ago
JSON representation
Workspace engineering intelligence — an AGENTS.md-based framework for agent-driven development
- Host: GitHub
- URL: https://github.com/yazilim-vip/nova-workspace
- Owner: yazilim-vip
- License: mit
- Created: 2026-04-20T07:29:32.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2026-04-27T12:54:40.000Z (about 2 months ago)
- Last Synced: 2026-04-27T14:06:05.643Z (about 2 months ago)
- Topics: agents-md, ai-agents, claude-code, developer-tools, nova, workspace
- Language: Go Template
- Homepage:
- Size: 308 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# NOVA — Workspace Engineering Intelligence
A 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.
NOVA 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.
**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.
## What you get
- **`AGENTS.md`** — the agent's identity, safety rules, and navigation protocol.
- **`SOUL.md`** — voice and depth, loaded only when the task demands it.
- **`.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).
- **`.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.
- **Framework procedures under `.ai/procedures//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:
- `onboarding` — guided workspace setup.
- `self-update` — deliberate upstream sync.
- `adapters` — generate per-platform steering, hooks, subagents.
- `ide` — editor setup. IntelliJ multi-module project; Neovim with `claudecode.nvim` MCP bridge.
- `terminal` — terminal multiplexer (tmux) and host-emulator settings Claude requires.
- `dream` — periodic memory consolidation pass over learnings + drift log.
- `personal-knowledge-management` — manages a personal knowledge vault under `notes/`.
- **`.ai/project-structure.md`** — NOVA's convention for a single project's AGENTS.md / `.ai/` layout. A reference doc.
- **`.ai/workspace/`** — the local workspace instance (gitignored; populated during onboarding) — workspace identity, repo map, infra config, accumulated learnings.
- **`git-repositories/`** — the clone convention (`//`; gitignored).
**Mental model:**
- `.ai/procedures//PROCEDURE.md` = NOVA's own framework procedures (workspace-bound workflows, listed in AGENTS.md table). Not portable agentskills.io skills.
- `.ai/*.md` = NOVA's conventions (read when context demands).
- `.ai/procedures/adapters/` = per-platform pointers + hooks + subagents (committed; runtime outputs like `.claude/`, `.kiro/` are gitignored, regenerable).
- `.ai/workspace/` = your local workspace state (gitignored). Identity overrides, repo map, infra config, learnings.
NOVA never writes into `.ai/workspace/` upstream — your local state stays yours.
## Why workspace-level, not repo-level?
Most 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.
## Why prose plus enforcement?
LLM 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:
- **Session-start broadcast** — workspace identity + nav protocol injected at position 0 (Claude `@`-imports, Kiro `inclusion: always` steering).
- **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.
- **Scoped activation** — entering `git-repositories//` auto-loads that repo's `AGENTS.md` (Kiro `fileMatch`; on Claude, delegated to the `repo-worker` subagent).
- **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).
- **Focused subagents** — `repo-worker` and `dream-worker` ship as fresh-context archetypes with the rulebook pre-walked at definition time.
The full contract lives at [.ai/enforcement.md](.ai/enforcement.md). Adapters are pointers, never copies — every rule still has one source of truth.
## Getting started
1. Clone this repo into a new workspace directory.
2. Open the workspace in your agent (Claude Code, Kiro, Cursor, Codex, etc.).
3. Say **"set up my workspace"** — NOVA will guide you through onboarding.
4. Say **"set up the \ adapter"** to generate platform-native steering, hooks, and subagents (`.claude/`, `.kiro/`).
5. (Optional) Clone your project repos into `git-repositories/` following the `//` convention.
Manual 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.
## What onboarding looks like
NOVA 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.
See 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.
## Bringing your own skills
Skills 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.
- **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//README.md` § "Skills" describes the native path.
- **Project skills** — domain-specific skills owned by one repo. Declared in the repo's own `AGENTS.md` and stored at the repo's choice (`/.ai/skills//SKILL.md` is one common convention, not required). Auto-loaded when the agent enters the repo.
Pick whichever tier(s) fit your workflow. Mix freely. See `AGENTS.md` § "Skills" and `.ai/project-structure.md` § "Project Skills" for details.
> 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.
**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.
Example skill frontmatter:
```markdown
---
name: my-skill
description: One-line description of what this skill does and when to use it.
metadata:
author: your-name
version: "0.1.0"
---
```
## Staying current with upstream
If you've forked NOVA, sync deliberately — don't blind-merge:
```bash
git remote add upstream https://github.com/yazilim-vip/nova-workspace.git
```
Then 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.
## Contributing upstream
If 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.
## Status
Early. 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.
## License
[MIT](./LICENSE) © yazilim.vip