@olives/devos 2.1.0

package/docs/SLASH_COMMANDS.md

@@ -0,0 +1,116 @@
+# Slash Commands Reference
+
+Slash commands are pre-configured triggers that route tasks to specific agents with predefined rules, tools, and prompts.
+
+## Command System Overview
+
+Commands are defined in `.agents/commands/`. When you use a slash command (e.g., `/review`), the Orchestrator reads the corresponding markdown file and routes the request to the target agent immediately.
+
+## Claude Code Integration
+
+Running `devos init` compiles the command definitions in `.agents/commands/` into `.claude/commands/`, so every command in this reference is natively available as a slash command inside Claude Code (e.g., typing `/review` in a Claude Code session). Pass `--no-claude` to `devos init` if you want to skip generating the `.claude/` integration files.
+
+## Schema Explanation
+
+Each command file uses YAML frontmatter to configure behavior:
+
+```yaml
+---
+name: command-name
+description: Short description shown in command picker
+agent: target-agent-name
+triage_level: TRIVIAL | STANDARD | CRITICAL
+workflow: standard | bugfix | inception | direct
+---
+
+# Command prompt body
+This is the pre-configured prompt sent to the agent.
+Use $ARGUMENTS to reference user input after the command.
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `name` | Yes | Command trigger name (without `/`) |
+| `description` | Yes | Human-readable description |
+| `agent` | Yes | Target agent (e.g., `qa`, `developer`) |
+| `triage_level` | Yes | `TRIVIAL`, `STANDARD`, or `CRITICAL` |
+| `workflow` | No | Which delivery workflow to follow. Defaults to `standard` |
+
+## Commands Reference
+
+### `/review`
+- **Description**: Request a comprehensive code review.
+- **Target Agent**: QA
+- **Triage Level**: STANDARD
+- **Workflow**: direct
+- **Usage**: `/review src/components/Button.tsx`
+
+### `/commit`
+- **Description**: Trigger the autonomous commit workflow.
+- **Target Agent**: Developer
+- **Triage Level**: TRIVIAL
+- **Workflow**: direct
+- **Usage**: `/commit Added the new button component`
+
+### `/test`
+- **Description**: Generate or execute tests for a module.
+- **Target Agent**: Tester
+- **Triage Level**: STANDARD
+- **Workflow**: direct
+- **Usage**: `/test src/utils/math.js`
+
+### `/secure`
+- **Description**: Request a security audit.
+- **Target Agent**: Security
+- **Triage Level**: STANDARD
+- **Workflow**: direct
+- **Usage**: `/secure`
+
+### `/research`
+- **Description**: Investigate docs, CVEs, or package info.
+- **Target Agent**: Researcher
+- **Triage Level**: TRIVIAL
+- **Workflow**: direct
+- **Usage**: `/research Next.js 14 App Router caching`
+
+### `/status`
+- **Description**: Summarize the current project state.
+- **Target Agent**: Orchestrator
+- **Triage Level**: TRIVIAL
+- **Workflow**: direct
+- **Usage**: `/status`
+
+### `/fix`
+- **Description**: Initiate the Bug Fix workflow.
+- **Target Agent**: Developer
+- **Triage Level**: STANDARD
+- **Workflow**: bugfix
+- **Usage**: `/fix The login button doesn't respond on mobile`
+
+### `/architect`
+- **Description**: Incept a new feature or project.
+- **Target Agent**: Architect
+- **Triage Level**: STANDARD
+- **Workflow**: inception
+- **Usage**: `/architect We need a new admin dashboard for user management`
+
+### `/refactor`
+- **Description**: Refactor code in the specified scope, with all existing tests passing and QA review before merge.
+- **Target Agent**: Developer
+- **Triage Level**: STANDARD
+- **Workflow**: standard
+- **Usage**: `/refactor Rewrite the auth module using the new Context API`
+
+### `/deploy`
+- **Description**: Trigger DevOps for deployment planning and execution.
+- **Target Agent**: DevOps
+- **Triage Level**: CRITICAL
+- **Workflow**: direct
+- **Usage**: `/deploy production`
+
+## Creating Custom Commands
+
+To create a new command:
+1. Create a `.md` file in `.agents/commands/`.
+2. Add the required YAML frontmatter.
+3. Add the instructions for the agent below the frontmatter.

package/docs/TUTORIAL.md

@@ -0,0 +1,75 @@
+# Dev-OS Tutorial
+
+Welcome to Dev-OS! This step-by-step guide will walk you through using the Engineering OS.
+
+## 1. What is Dev-OS?
+
+Dev-OS is an AI-augmented Engineering Operating System. Instead of a single AI assistant, you have a full development team comprising an Orchestrator, Developer, QA, Tester, Security, and more. They follow strict workflows, require human approval for crucial steps, and prevent common AI mistakes through mechanical gates.
+
+## 2. Setting up Dev-OS
+
+1. **Install Dev-OS**: From your project root, run `npx @olives/devos init` (see [Getting Started](GETTING_STARTED.md) for all installation options). This installs `.agents/`, generates the Claude Code integration in `.claude/`, and sets up your coding standards.
+2. **Install hooks**: Run `.agents/scripts/install-hooks.sh`. This sets up Git hooks.
+3. **Verify gitleaks**: The hook enforces secret scanning using `gitleaks`. Any commits containing secrets will be mechanically rejected.
+4. **Check health**: Run `devos doctor` — it must report all required checks passing.
+
+## 3. Understanding the Agent Roster
+
+You communicate primarily with the **Orchestrator**. 
+The Orchestrator delegates to:
+- **Architect**: Designs the system and requirements.
+- **Developer**: Writes the code.
+- **QA, Tester, Security**: The parallel quality gate.
+- **DBA, DevOps**: Infrastructure and databases.
+- **Memory Manager & Release Manager**: Handles state, context, and versioning.
+
+For a full breakdown, see `../.agents/AGENTS.md`.
+
+## 4. Using Slash Commands
+
+Slash commands let you explicitly trigger a workflow or a specific agent.
+
+*Examples:*
+- `/test src/auth/login.js` -> Triggers the Tester to write/run tests for the login module.
+- `/secure` -> Asks the Security agent to audit the codebase.
+- `/architect Build a user profile page` -> Runs the `grill-me` skill to define requirements.
+
+See [Slash Commands Reference](SLASH_COMMANDS.md) for more details.
+
+## 5. Understanding the Workflow
+
+### Standard Feature Delivery
+1. Orchestrator delegates to Developer.
+2. Developer writes code.
+3. **Parallel Gate**: QA checks standards, Tester runs/writes tests, Security scans for vulnerabilities.
+4. Human approves.
+
+### Bug Fix
+1. Researcher finds the root cause.
+2. Developer fixes it.
+3. Tester writes a regression test.
+4. QA approves.
+5. Human approves.
+
+## 6. Memory System
+
+Dev-OS maintains its own context to prevent token overload and "forgetting".
+- `CURRENT_STATE.md`: Tracks the current state of the project.
+- `LESSONS.md`: Episodic memory of past mistakes and architectural decisions.
+- **Pinned Rules**: Always present in the agent's context.
+
+## 7. Commit Workflow (commit.sh)
+
+Agents cannot run raw `git commit`. Changes are staged with `git add`, then the human runs `.agents/scripts/commit.sh`. The script:
+1. Prompts for the human approval token.
+2. Prompts for the commit type and message.
+3. Exports `DEVOS_COMMIT_APPROVED`.
+4. Runs `git commit`, which passes through the Git pre-commit hook.
+
+Note: the script does **not** stage files — run `git add` before invoking it.
+
+## 8. Best Practices and Tips
+
+- **Review the plans**: Always read what the DevOps or DBA agents plan to do before approving.
+- **Use /status**: If you lose track, type `/status` to have the Orchestrator summarize the situation from `CURRENT_STATE.md`.
+- **Let them loop, but not forever**: Agents have a Circuit Breaker (3 iterations). If they fail 3 times, they will escalate to you.

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@olives/devos",
+  "version": "2.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Olives Technologies Engineering OS — Autonomous Multi-Agent AI Engineering Environment",
+  "bin": {
+    "devos": "bin/devos.js",
+    "olives-devos": "bin/devos.js",
+    "devos-init": "bin/devos.js"
+  },
+  "scripts": {
+    "start": "node ./bin/devos.js",
+    "test": "node ./scripts/smoke-test.js",
+    "prepublishOnly": "node ./scripts/smoke-test.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/olitech1010/dev-os.git"
+  },
+  "homepage": "https://github.com/olitech1010/dev-os#readme",
+  "bugs": {
+    "url": "https://github.com/olitech1010/dev-os/issues"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "claude",
+    "gemini",
+    "cursor",
+    "multi-agent",
+    "dev-os",
+    "skills",
+    "langgraph",
+    "llm",
+    "orchestrator"
+  ],
+  "author": "Clement Olives — Olives Technologies",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    ".agents/",
+    "docs/",
+    "CODING_STANDARDS.md",
+    "README.md",
+    "LICENSE",
+    "VERSION"
+  ]
+}

package/scripts/smoke-test.js

@@ -0,0 +1,167 @@
+#!/usr/bin/env node
+
+/**
+ * Dev-OS smoke test (zero external dependencies).
+ * Run with: npm test
+ *
+ * Verifies the shipped package end-to-end:
+ *   1. `devos init` installs a working environment into a clean directory
+ *   2. `devos doctor` passes there (exit 0) and fails in an empty directory (exit 1)
+ *   3. Re-running init creates a .agents/_backup/<timestamp>/ backup
+ *   4. Content integrity: command frontmatter points at real agents, skills are
+ *      well-formed, and skill paths referenced in prose resolve on disk.
+ */
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+const CLI = path.join(ROOT, 'bin', 'devos.js');
+
+let failures = 0;
+function check(label, ok, detail) {
+  if (ok) {
+    console.log(`[ PASS ] ${label}`);
+  } else {
+    failures++;
+    console.error(`[ FAIL ] ${label}${detail ? ` — ${detail}` : ''}`);
+  }
+}
+
+function runCli(args, cwd) {
+  return spawnSync(process.execPath, [CLI, ...args], { cwd, encoding: 'utf8' });
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return null;
+  const data = {};
+  match[1].split(/\r?\n/).forEach((line) => {
+    const idx = line.indexOf(':');
+    if (idx > 0) data[line.slice(0, idx).trim()] = line.slice(idx + 1).trim();
+  });
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// 1. init into a clean project
+// ---------------------------------------------------------------------------
+const proj = fs.mkdtempSync(path.join(os.tmpdir(), 'devos-smoke-'));
+const empty = fs.mkdtempSync(path.join(os.tmpdir(), 'devos-empty-'));
+
+try {
+  const init = runCli(['init', '--existing', '--stack', 'universal', '--quiet'], proj);
+  check('devos init exits 0', init.status === 0, (init.stderr || init.stdout || '').trim().slice(0, 300));
+
+  check('.agents/ installed', fs.existsSync(path.join(proj, '.agents', 'AGENTS.md')));
+  check('CODING_STANDARDS.md installed', fs.existsSync(path.join(proj, 'CODING_STANDARDS.md')));
+  check('CLAUDE.md bootstrapped', fs.existsSync(path.join(proj, 'CLAUDE.md')));
+
+  const agentCount = fs.existsSync(path.join(proj, '.agents', 'agents'))
+    ? fs.readdirSync(path.join(proj, '.agents', 'agents')).filter((f) => f.endsWith('.md')).length
+    : 0;
+  check(`agent personas installed (found ${agentCount})`, agentCount >= 10);
+
+  const claudeAgents = fs.existsSync(path.join(proj, '.claude', 'agents'))
+    ? fs.readdirSync(path.join(proj, '.claude', 'agents')).filter((f) => f.endsWith('.md')).length
+    : 0;
+  check('.claude/agents generated, one per persona', claudeAgents === agentCount, `${claudeAgents} vs ${agentCount}`);
+
+  const claudeCommands = fs.existsSync(path.join(proj, '.claude', 'commands'))
+    ? fs.readdirSync(path.join(proj, '.claude', 'commands')).filter((f) => f.endsWith('.md')).length
+    : 0;
+  check(`.claude/commands generated (found ${claudeCommands})`, claudeCommands >= 9);
+
+  const generated = path.join(proj, '.claude', 'agents');
+  if (claudeAgents > 0) {
+    const sample = fs.readFileSync(path.join(generated, fs.readdirSync(generated)[0]), 'utf8');
+    const fm = parseFrontmatter(sample);
+    check('generated subagents have name + description frontmatter', Boolean(fm && fm.name && fm.description));
+  }
+
+  // -------------------------------------------------------------------------
+  // 2. doctor: passes in the project, fails in an empty directory
+  // -------------------------------------------------------------------------
+  const doctorOk = runCli(['doctor', '--quiet'], proj);
+  check('devos doctor exits 0 in initialized project', doctorOk.status === 0, (doctorOk.stdout || '').trim().slice(-300));
+
+  const doctorFail = runCli(['doctor', '--quiet'], empty);
+  check('devos doctor exits non-zero in empty directory', doctorFail.status !== 0);
+
+  // -------------------------------------------------------------------------
+  // 3. re-init creates a backup
+  // -------------------------------------------------------------------------
+  const reinit = runCli(['init', '--existing', '--stack', 'universal', '--quiet'], proj);
+  const backupDir = path.join(proj, '.agents', '_backup');
+  const backups = fs.existsSync(backupDir) ? fs.readdirSync(backupDir) : [];
+  check('re-running init backs up .agents/ to _backup/<timestamp>/', reinit.status === 0 && backups.length >= 1);
+
+  // -------------------------------------------------------------------------
+  // 3b. devos update safely refreshes components
+  // -------------------------------------------------------------------------
+  const update = runCli(['update', '--quiet'], proj);
+  check('devos update exits 0', update.status === 0, (update.stderr || update.stdout || '').trim().slice(0, 300));
+  const claudeContent = fs.readFileSync(path.join(proj, 'CLAUDE.md'), 'utf8');
+  check('CLAUDE.md contains Hard Rules digest', claudeContent.includes('Hard Rules Digest'));
+} finally {
+  fs.rmSync(proj, { recursive: true, force: true });
+  fs.rmSync(empty, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// 4. content integrity of the shipped sources
+// ---------------------------------------------------------------------------
+const agentsDir = path.join(ROOT, '.agents', 'agents');
+const commandsDir = path.join(ROOT, '.agents', 'commands');
+const skillsDir = path.join(ROOT, '.agents', 'skills');
+
+const agentNames = fs.readdirSync(agentsDir).filter((f) => f.endsWith('.md')).map((f) => f.replace('.md', ''));
+
+fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md') && f !== 'README.md').forEach((file) => {
+  const fm = parseFrontmatter(fs.readFileSync(path.join(commandsDir, file), 'utf8'));
+  check(`command ${file} has valid frontmatter`, Boolean(fm && fm.name && fm.description && fm.agent));
+  if (fm && fm.agent) {
+    check(`command ${file} targets a real agent (${fm.agent})`, agentNames.includes(fm.agent));
+  }
+});
+
+const skillDirs = fs.readdirSync(skillsDir).filter((f) => {
+  if (f === '_backup') return false;
+  return fs.statSync(path.join(skillsDir, f)).isDirectory();
+});
+const skillsMissingManifest = skillDirs.filter((d) => !fs.existsSync(path.join(skillsDir, d, 'SKILL.md')));
+check(`all ${skillDirs.length} skills have a SKILL.md`, skillsMissingManifest.length === 0, skillsMissingManifest.join(', '));
+
+// Every `.agents/skills/<name>/` path mentioned in first-party prose must exist
+const proseFiles = [
+  path.join(ROOT, '.agents', 'AGENTS.md'),
+  path.join(ROOT, '.agents', 'README.md'),
+  ...fs.readdirSync(agentsDir).map((f) => path.join(agentsDir, f)),
+  ...fs.readdirSync(commandsDir).filter((f) => f.endsWith('.md')).map((f) => path.join(commandsDir, f))
+];
+const badRefs = [];
+proseFiles.forEach((file) => {
+  const content = fs.readFileSync(file, 'utf8');
+  const re = /\.agents\/skills\/([A-Za-z0-9._-]+)\//g;
+  let m;
+  while ((m = re.exec(content)) !== null) {
+    if (m[1] !== '_backup' && !skillDirs.includes(m[1])) {
+      badRefs.push(`${path.relative(ROOT, file)} -> ${m[1]}`);
+    }
+  }
+});
+check('all referenced skill paths resolve on disk', badRefs.length === 0, badRefs.join('; '));
+
+// Every stack the CLI offers must have a template (universal uses root CODING_STANDARDS.md)
+['nextjs', 'laravel', 'django', 'react-native', 'express', 'fastapi'].forEach((stack) => {
+  check(`stack template exists: ${stack}`, fs.existsSync(path.join(skillsDir, 'stacks', `${stack}.md`)));
+});
+
+console.log('');
+if (failures > 0) {
+  console.error(`[ FAIL ] Smoke test finished with ${failures} failure(s).`);
+  process.exit(1);
+}
+console.log('[ OK ] Smoke test passed.');