@vsem/ai 0.1.0

package/README.md

@@ -0,0 +1,28 @@
+# @vsem/ai
+
+Install or sync a vsem-framework workspace: creates `.ai/` (rules, roles, tasks,
+decisions, incidents, index), `CLAUDE.md`, `code/`, `materials/`, and sets up git
+with your personal branch.
+
+## Usage
+
+```bash
+cd my-project
+npx @vsem/ai@latest
+```
+
+Runs against the current directory by default. Optional arguments:
+
+```bash
+npx @vsem/ai@latest [target-dir] [--branch <name>] [--force]
+```
+
+- `target-dir` — install into this directory instead of the current one (created if missing).
+- `--branch <name>` — personal branch name (default: your `git config --global user.name`, or `dev`).
+- `--force` — also overwrite project-owned files (`.ai/project.md`, `.ai/plan.md`, task/decision/incident indexes), resetting them to placeholders. Without this flag, reruns only update framework-owned files (`.ai/rules/`, `.ai/roles/`, `CLAUDE.md`) and never touch your own project state.
+
+## Updating an existing workspace
+
+Rerun `npx @vsem/ai@latest` (without `--force`) inside an already-bootstrapped
+workspace to pick up new roles or rule changes published in later versions — your
+`project.md`, `plan.md`, and tasks are left untouched.

package/bin/cli.js

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+'use strict';
+
+// Install or sync a vsem-framework workspace.
+//
+// This script contains NO framework content (no role text, no rule text). It only
+// knows HOW to install the structure: it copies two template trees from
+// ../templates next to this script into the target workspace, substituting
+// {{VAR}} placeholders, and sets up git.
+//
+// - templates/system/  -> framework-owned files (CLAUDE.md, .ai/rules/*, .ai/roles/*).
+//   Always re-copied (overwritten) on every run. To add a new role, drop a file under
+//   templates/system/.ai/roles/, bump the package version and publish - no code
+//   change needed here.
+// - templates/scaffold/ -> project-owned starting points (.ai/project.md, .ai/plan.md,
+//   .ai/tasks/_index.md, etc). Only written if missing, so a rerun never clobbers the
+//   user's own project state. Pass --force to overwrite scaffold files too.
+//
+// Usage:
+//   npx @vsem/ai@latest [target-dir] [--branch <name>] [--force]
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const FRAMEWORK_VERSION = '0.1.0';
+const PACKAGE_DIR = path.join(__dirname, '..');
+const TEMPLATES_DIR = path.join(PACKAGE_DIR, 'templates');
+const SYSTEM_DIR = path.join(TEMPLATES_DIR, 'system');
+const SCAFFOLD_DIR = path.join(TEMPLATES_DIR, 'scaffold');
+
+function parseArgs(argv) {
+    const opts = { target: null, branch: null, force: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--force') {
+            opts.force = true;
+        } else if (a === '--branch') {
+            opts.branch = argv[++i] || null;
+        } else if (a.startsWith('--branch=')) {
+            opts.branch = a.slice('--branch='.length);
+        } else if (!a.startsWith('-') && opts.target === null) {
+            opts.target = a;
+        }
+    }
+    return opts;
+}
+
+function walkFiles(dir) {
+    const results = [];
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            results.push(...walkFiles(full));
+        } else if (entry.isFile()) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+
+// Copies every file under srcRoot into destRoot, preserving relative paths.
+// Strips a trailing ".tmpl" from destination file names. Replaces {{KEY}}
+// tokens. Only overwrites existing destination files when overwrite is true;
+// otherwise leaves them untouched (used for scaffold/ files).
+function copyTemplateTree(srcRoot, destRoot, vars, overwrite) {
+    if (!fs.existsSync(srcRoot)) return;
+    for (const file of walkFiles(srcRoot)) {
+        let rel = path.relative(srcRoot, file);
+        if (rel.endsWith('.tmpl')) {
+            rel = rel.slice(0, -'.tmpl'.length);
+        }
+        const dest = path.join(destRoot, rel);
+
+        if (fs.existsSync(dest) && !overwrite) {
+            continue;
+        }
+
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        let content = fs.readFileSync(file, 'utf8');
+        for (const key of Object.keys(vars)) {
+            content = content.split(`{{${key}}}`).join(vars[key]);
+        }
+        fs.writeFileSync(dest, content, 'utf8');
+    }
+}
+
+function ensureEmptyDirPlaceholder(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+    if (fs.readdirSync(dir).length === 0) {
+        fs.writeFileSync(path.join(dir, '.gitkeep'), '');
+    }
+}
+
+function tryGit(args, cwd) {
+    try {
+        return { ok: true, out: execFileSync('git', args, { cwd, encoding: 'utf8' }) };
+    } catch (err) {
+        return { ok: false, out: '', err };
+    }
+}
+
+function main() {
+    if (!fs.existsSync(SYSTEM_DIR)) {
+        console.error(`Templates not found at ${SYSTEM_DIR}. This script must ship together with templates/.`);
+        process.exit(1);
+    }
+
+    const args = parseArgs(process.argv.slice(2));
+    const target = path.resolve(args.target || process.cwd());
+
+    fs.mkdirSync(target, { recursive: true });
+    const aiDir = path.join(target, '.ai');
+    const workspaceName = path.basename(target);
+    const isRerun = fs.existsSync(aiDir);
+
+    let branch = args.branch;
+    if (!branch) {
+        const cfg = tryGit(['config', '--global', 'user.name'], target);
+        if (cfg.ok && cfg.out.trim()) {
+            branch = cfg.out.trim().toLowerCase().replace(/\s+/g, '-').replace(/^-+|-+$/g, '');
+        }
+        if (!branch) branch = 'dev';
+    }
+
+    const vars = { WORKSPACE_NAME: workspaceName, FRAMEWORK_VERSION: FRAMEWORK_VERSION };
+
+    copyTemplateTree(SYSTEM_DIR, target, vars, true);
+    copyTemplateTree(SCAFFOLD_DIR, target, vars, args.force);
+
+    for (const rel of ['code', 'materials', path.join('.ai', 'memory')]) {
+        ensureEmptyDirPlaceholder(path.join(target, rel));
+    }
+
+    if (isRerun) {
+        console.log(`[ok] Workspace synced at ${target} (system files updated; scaffold files kept unless --force)`);
+    } else {
+        console.log(`[ok] Workspace structure created at ${target}`);
+    }
+
+    const gitCheck = tryGit(['--version'], target);
+    if (!gitCheck.ok) {
+        console.log('[warn] git not found in PATH - skipping git init.');
+        return;
+    }
+
+    if (!fs.existsSync(path.join(target, '.git'))) {
+        tryGit(['init', '-q'], target);
+        console.log('[ok] git init');
+    }
+
+    const currentBranchResult = tryGit(['branch', '--show-current'], target);
+    const currentBranch = currentBranchResult.ok ? currentBranchResult.out.trim() : '';
+
+    if (currentBranch !== branch) {
+        const branchExists = tryGit(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`], target).ok;
+        if (branchExists) {
+            tryGit(['checkout', '-q', branch], target);
+        } else {
+            tryGit(['checkout', '-q', '-b', branch], target);
+        }
+        console.log(`[ok] branch '${branch}' is active`);
+    }
+
+    tryGit(['add', '-A'], target);
+    const noChanges = tryGit(['diff', '--cached', '--quiet'], target).ok;
+
+    if (!noChanges) {
+        const msg = isRerun ? 'chore: sync vsem-framework system files' : 'chore: bootstrap vsem-framework workspace';
+        tryGit(['commit', '-q', '-m', msg], target);
+        console.log(`[ok] commit created: ${msg}`);
+    } else {
+        console.log('[skip] nothing to commit (already up to date)');
+    }
+}
+
+main();

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@vsem/ai",
+  "version": "0.1.0",
+  "description": "Install or sync a vsem-framework workspace (.ai/ structure, roles, rules) via npx.",
+  "bin": {
+    "vsem-ai": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=14"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "ai",
+    "framework",
+    "scaffolding",
+    "claude"
+  ]
+}

package/templates/scaffold/.ai/decisions/_index.md

@@ -0,0 +1,3 @@
+# Decision Log
+
+> One entry = one decision. Maintained by ProjectManager.

package/templates/scaffold/.ai/incidents/_index.md

@@ -0,0 +1,3 @@
+# Incident Log
+
+> Failures/errors in role work - separate from the decision log.

package/templates/scaffold/.ai/index/README.md

@@ -0,0 +1,3 @@
+# Document / Code Graph Index
+
+> Mechanism not chosen yet (see the framework's own roadmap). Empty for now.

package/templates/scaffold/.ai/plan.md.tmpl

@@ -0,0 +1,8 @@
+# Plan - {{WORKSPACE_NAME}}
+
+> TODO: filled in by the PM role after `.ai/project.md` is approved.
+> Decomposition happens incrementally as the project progresses, not all at
+> once at the start.
+
+## Phase 0
+- [ ] TODO

package/templates/scaffold/.ai/project.md.tmpl

@@ -0,0 +1,17 @@
+# Project - {{WORKSPACE_NAME}}
+
+> TODO: filled in by the PM role after a requirements dialogue with the user
+> (goal, audience, constraints, MVP scope). Source material - see `materials/`.
+
+## Vision
+TODO
+
+## Goals
+TODO
+
+## Non-goals
+TODO
+
+## Key decisions log
+| Date | Decision | Reason |
+|------|----------|--------|

package/templates/scaffold/.ai/tasks/_index.md

@@ -0,0 +1,8 @@
+# Tasks Index
+
+> Auto-generated summary of `.ai/tasks/*.md`, so roles don't need to read every
+> file - saves tokens (see the ContextManager role). Task format - see
+> `.ai/rules/tasks-format.md`.
+
+| id | title | owner_role | status | priority |
+|----|-------|------------|--------|----------|

package/templates/system/.ai/roles/architect.md

@@ -0,0 +1,14 @@
+---
+role_id: architect
+---
+
+# Architect
+
+## Responsible for
+Architectural and technical decisions at project/module level.
+
+## Can block
+Developer (until the decision is reconsidered).
+
+## Escalates to the human when
+The decision is irreversible or affects multiple code repositories at once.

package/templates/system/.ai/roles/context-manager.md

@@ -0,0 +1,14 @@
+---
+role_id: context-manager
+---
+
+# ContextManager (system role)
+
+## Responsible for
+Assembles the minimally sufficient context for a role+task (token economy).
+
+## Can block
+-
+
+## Escalates to the human when
+Session token budget is at risk of being exceeded.

package/templates/system/.ai/roles/conventions-guardian.md

@@ -0,0 +1,14 @@
+---
+role_id: conventions-guardian
+---
+
+# ConventionsGuardian
+
+## Responsible for
+Checks that code/documents comply with framework conventions; guards the hard rule "never change .ai/ structure without confirmation".
+
+## Can block
+Any role, if it violates the .ai/ structure or conventions.
+
+## Escalates to the human when
+A violation of .ai/ structure is found - escalate immediately, without attempting to fix it itself.

package/templates/system/.ai/roles/designer.md

@@ -0,0 +1,14 @@
+---
+role_id: designer
+---
+
+# Designer
+
+## Responsible for
+UX/UI decisions, design mockups.
+
+## Can block
+-
+
+## Escalates to the human when
+No approved materials to rely on (no spec/references).

package/templates/system/.ai/roles/developer.md

@@ -0,0 +1,14 @@
+---
+role_id: developer
+---
+
+# Developer
+
+## Responsible for
+Implementation of code in code/* per task.
+
+## Can block
+-
+
+## Escalates to the human when
+The task is ambiguous and requires an architectural decision that does not exist yet.

package/templates/system/.ai/roles/indexer-librarian.md

@@ -0,0 +1,14 @@
+---
+role_id: indexer-librarian
+---
+
+# Indexer/Librarian
+
+## Responsible for
+Maintains the document/code index/graph in .ai/index/ (exact mechanism still being designed).
+
+## Can block
+-
+
+## Escalates to the human when
+Found a contradiction between documents it cannot resolve on its own.

package/templates/system/.ai/roles/project-manager.md

@@ -0,0 +1,14 @@
+---
+role_id: project-manager
+---
+
+# ProjectManager (PM)
+
+## Responsible for
+Task decomposition and prioritization (incrementally, as the project progresses), final decision in role conflicts, maintaining the decision log, distributing work across roles.
+
+## Can block
+Can pause any role in case of priority conflicts.
+
+## Escalates to the human when
+Not confident in resolving the conflict itself; the question affects MVP scope/deadlines.

package/templates/system/.ai/roles/reviewer-qa.md

@@ -0,0 +1,14 @@
+---
+role_id: reviewer-qa
+---
+
+# Reviewer/QA
+
+## Responsible for
+Quality check of task results before closing (tests, linter, review).
+
+## Can block
+Developer (task stays open until the gate is passed).
+
+## Escalates to the human when
+The found issue is systemic (not scoped to a single task).

package/templates/system/.ai/roles/technical-writer.md

@@ -0,0 +1,14 @@
+---
+role_id: technical-writer
+---
+
+# TechnicalWriter
+
+## Responsible for
+Documentation for humans (README, guides) outside .ai/ - inside .ai/ the structure itself is the documentation.
+
+## Can block
+-
+
+## Escalates to the human when
+Not enough information from other roles to describe the feature.

package/templates/system/.ai/roles/tester.md

@@ -0,0 +1,14 @@
+---
+role_id: tester
+---
+
+# Tester
+
+## Responsible for
+Test scenarios and running them (may overlap with Reviewer/QA - the split is refined as the project evolves).
+
+## Can block
+-
+
+## Escalates to the human when
+Cannot reproduce/confirm the bug.

package/templates/system/.ai/rules/core.md

@@ -0,0 +1,28 @@
+---
+framework_version: "{{FRAMEWORK_VERSION}}"
+---
+
+# Core Rules (vsem-framework)
+
+1. **Never change the structure of `.ai/`** (create/delete/rename top-level
+   folders inside it) without explicit human confirmation. This is the main rule
+   for every role/agent working in this workspace.
+2. Roles work within a limited, role-scoped context - do not read the whole
+   repository unless the task requires it. Context for a task is assembled by
+   ContextManager.
+3. Conflicts between roles are resolved by ProjectManager; the decision is
+   recorded in `.ai/decisions/`. If PM itself is not sure, escalate to the human.
+4. Autonomy by default - the framework acts on its own. Stop and ask the human
+   when:
+   - about to merge the personal branch into `main`;
+   - the operation deletes data or is irreversible;
+   - an external access/secret/integration is required;
+   - the decision is architectural at the whole-project level;
+   - the role itself is not sure about the decision.
+5. In autonomous mode, commits go to the user's personal branch, never to `main`.
+6. `code/*` is code only (git submodules). `materials/` is raw input from the
+   user. `.ai/` holds the entire methodology and working state of the project.
+7. A task is not closed (`status: done`) without passing its quality gate, if
+   one is required for it (see `.ai/roles/reviewer-qa.md`).
+
+See also `.ai/project.md` (this project's description) and `.ai/plan.md` (this project's plan).

package/templates/system/.ai/rules/tasks-format.md

@@ -0,0 +1,36 @@
+# Task Format
+
+One file = one task, in `.ai/tasks/`. File name: `<id>-<short-slug>.md`
+(id = zero-padded sequence number, e.g. `0001`).
+
+## Frontmatter
+
+```yaml
+---
+id: "0001"
+title: "Short task title"
+owner_role: developer        # one of the roles in .ai/roles/, lowercase
+status: todo                 # todo | in_progress | blocked-on-human | blocked-on-dependency | blocked-on-external | in_review | done
+priority: must                # must | nice
+depends_on: []                 # ids of blocking tasks, e.g. ["0002"]
+linked_files:                   # paths to files/modules this task touches
+  - code/backend/src/auth/
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+```
+
+## Body
+- **Description** - what needs to be done and why.
+- **Acceptance criteria** - short checklist Reviewer/QA uses to confirm the task is done.
+- **Notes** - optional work log.
+
+## Status transitions
+`todo -> in_progress -> in_review -> done`
+Side branches: `blocked-on-*` (from any active status, back to `in_progress` once unblocked).
+
+## Who sets what
+- `priority` - ProjectManager.
+- `owner_role` - ProjectManager, during decomposition.
+- `status` - the owning role, as work progresses; moving to `done` requires
+  passing the quality gate (Reviewer/QA) if one applies to the task.

package/templates/system/CLAUDE.md.tmpl

@@ -0,0 +1,8 @@
+# {{WORKSPACE_NAME}}
+
+This project is managed by vsem-framework.
+Work according to the rules and structure in `.ai/`.
+Start with `.ai/rules/core.md` and `.ai/project.md`.
+
+**Hard rule:** never modify the top-level structure of `.ai/` (create/delete/rename
+top-level folders inside it) without explicit human confirmation.