@adityaaria/agent-os 1.0.0

package/core/AUTO_PROJECT_DETECTOR.md

@@ -0,0 +1,99 @@
+# Auto Project Detector
+
+## Purpose
+
+The `AUTO_PROJECT_DETECTOR.md` serves as the silent, invisible observer within the Agent OS architecture. Its primary purpose is to constantly monitor the state of the user's workspace and dynamically determine if the Agent has enough accurate context to safely execute a task.
+
+By fully automating the detection phase, this module entirely eliminates the historical requirement for developers to manually run initialization commands such as `ANALYZE PROJECT`. It transforms the framework into a seamless, "Zero Configuration" environment where a user can clone a repository and instantly type a command like `BUG: fix header` with zero friction.
+
+## Responsibilities
+
+This module is entrusted with several critical, background responsibilities:
+
+1. **Existence Verification**: It must verify whether the `.agent-os/project/` directory exists and contains valid markdown templates.
+2. **Context Monitoring**: It must monitor the core root configuration files of the project to track significant architectural shifts.
+3. **Execution Interception**: It must possess the authority to temporarily pause the user's primary task (e.g., a bug fix) to perform required onboarding tasks.
+4. **Silent Operation**: It must perform its duties without prompting the user for permission, ensuring a frictionless developer experience.
+
+## Detection Scope
+
+The Auto Project Detector scans specific boundaries to understand the workspace. The scope of detection includes, but is not limited to:
+
+- Package Manager Definitions (`package.json`, `pnpm-workspace.yaml`, `yarn.lock`)
+- Backend Environment Configs (`pom.xml`, `go.mod`, `requirements.txt`, `composer.json`)
+- Container and Deployment Configs (`docker-compose.yml`, `Dockerfile`, `k8s/`)
+- Directory Structures (e.g., detecting an `apps/` and `packages/` folder indicates a Monorepo pattern)
+
+## Project Knowledge Check
+
+When an agent receives a prompt (such as `BUG:`, `ENHANCEMENT:`, `NEW PAGE:`, `AUDIT:`, or `TEST:`), the detector must perform an immediate Project Knowledge Check.
+
+This check involves reading the `.agent-os/project/` folder. 
+If the folder is completely missing, or if it lacks core templates like `TECH_STACK.md` or `ARCHITECTURE.md`, the detector flags the workspace as "Unknown".
+
+An "Unknown" workspace is highly dangerous for an LLM to modify, as it leads to hallucinations and incorrect architectural assumptions. Therefore, the knowledge check is a mandatory, non-skippable gate.
+
+## Multi-Root Workspace Detection
+
+If the Agent operates inside an `.agent-os-workspace` folder, the detector must prioritize reading the `WORKSPACE_MAP.md` file.
+The detector must treat all independent folders defined in the map as a single, unified project environment.
+Any structural shifts (such as dependency changes) inside *any* of the mapped folders will trigger the `KNOWLEDGE_VALIDATOR.md`.
+
+## Change Detection
+
+If the Project Knowledge Check passes (i.e., the `.agent-os/project/` folder exists), the detector moves to Change Detection.
+
+This phase involves comparing the existing `TECH_STACK.md` against the actual, current state of the repository's dependency files.
+For example, if the documentation states the project uses `Express.js`, but the detector sees a new `nestjs/core` package in the `package.json`, it flags a structural shift.
+
+If a major shift is detected, the detector escalates the issue to the `KNOWLEDGE_VALIDATOR.md` for deeper inspection.
+
+## Auto-Onboarding Trigger
+
+If the Project Knowledge Check fails (the workspace is "Unknown"), the detector automatically triggers the Auto-Onboarding sequence.
+
+**Rule**: The user *does not need* to run `ANALYZE PROJECT`. The detector must silently invoke the `AGENT_OS_BOOTSTRAP.md` module in the background.
+
+The Bootstrap module will dynamically map the entire project, identify the frameworks, and scaffold the necessary markdown templates in `.agent-os/project/`. Once this process is complete, the detector releases the hold on the original task.
+
+## Pass-through Rules
+
+To ensure maximum speed and minimal latency for the developer, the detector must follow strict Pass-through Rules:
+
+1. If `.agent-os/project/` exists and is fully populated...
+2. AND no major structural shifts are detected in the root configurations...
+3. THEN the detector must instantly pass execution control back to the `SKILL_ORCHESTRATOR.md` without any further background processing.
+
+## Failure Handling
+
+In the rare event that the Auto Project Detector cannot read the file system (e.g., due to strict OS permission issues) or if the Auto-Onboarding process fails catastrophically, the detector must execute its failure protocol:
+
+1. Terminate the active task.
+2. Inform the user that the workspace context could not be mapped securely.
+3. Suggest verifying directory permissions or checking for corrupted config files.
+
+## Examples
+
+### Scenario: First Time Usage
+```txt
+USER: ENHANCEMENT: Add a dark mode toggle to the navbar.
+DETECTOR: Intercepting request.
+DETECTOR: Scanning for `.agent-os/project/`... [Not Found].
+DETECTOR: Triggering AGENT_OS_BOOTSTRAP.md silently.
+BOOTSTRAP: Project mapped successfully.
+DETECTOR: Knowledge verified. Releasing task to SKILL_ORCHESTRATOR.
+```
+
+### Scenario: Returning User
+```txt
+USER: BUG: The API returns a 404 on the user route.
+DETECTOR: Intercepting request.
+DETECTOR: Scanning for `.agent-os/project/`... [Found].
+DETECTOR: Change Detection... [No major structural shifts found].
+DETECTOR: Pass-through granted. Releasing task immediately.
+```
+
+## Notes
+
+> [!NOTE]
+> The Auto Project Detector is the absolute bedrock of the V2 Zero Configuration philosophy. By guaranteeing that context is always present and accurate, it allows the LLM to focus 100% of its reasoning capabilities on the user's actual coding problem, rather than wasting tokens trying to guess the environment.

package/core/COMPLIANCE_GATE.md

@@ -0,0 +1,19 @@
+# COMPLIANCE_GATE
+
+## Purpose
+Enforces mandatory pre-execution rules to ensure the Agent OS framework operates deterministically. This file acts as the absolute barrier before any codebase changes or deep analysis occurs.
+
+## Mandatory Rules
+
+Before executing any `BUG`, `AUDIT`, `ENHANCEMENT`, `NEW PAGE`, or `TEST` task, the agent MUST strictly adhere to the following sequence:
+
+1. **Load Entrypoint:** Agent MUST load `ENTRYPOINT.md`.
+2. **Load Workspace:** Agent MUST load `WORKSPACE_MAP.md` if available.
+3. **Validate Knowledge:** Agent MUST validate `.agent-os/project/`.
+4. **Auto-Onboarding:** If project knowledge is missing or incomplete, agent MUST run `project-onboarding` automatically.
+5. **Load Skill:** Agent MUST load the matching skill before analyzing source code.
+6. **Pass Checklist:** Agent MUST not produce a final answer before the compliance checklist passes.
+
+## Explicit Execution Block
+> [!CAUTION]
+> DO NOT perform direct file audit, direct bug fix, or direct code change before Agent OS compliance gate passes.

package/core/FRAMEWORK_AUDITOR.md

@@ -0,0 +1,35 @@
+# Framework Auditor
+
+## Purpose
+To provide Agent OS with the capability to perform self-healing diagnostics, ensuring the local instance remains structurally sound, secure, and production-ready.
+
+## Responsibilities
+- Audit repository structure ensuring all required files exist.
+- Audit skills for missing `workflow.md`, `checklist.md`, or `examples.md`.
+- Audit project onboarding templates for dead or empty documentation.
+- Audit IDE adapters and installer scripts for version drift.
+- Generate a Framework Health Score (0-100).
+
+## Workflow
+1. **Trigger Recognition**: User invokes `AUDIT FRAMEWORK`.
+2. **Scan Structure**: Agent verifies existence of `core/`, `skills/`, `templates/`, `adapters/`.
+3. **Scan Skills**: For each directory in `skills/`, agent verifies standard file compliance.
+4. **Scan Knowledge**: Agent checks `.agent-os/project/` for empty or missing mandatory templates.
+5. **Score Generation**: Agent calculates a percentage score based on missing constraints.
+6. **Self-Healing**: If a critical file is missing or malformed, the agent proposes regenerating it.
+7. **Report**: Agent outputs the `Framework Health Score` to the user.
+
+## Examples
+```txt
+USER: AUDIT FRAMEWORK
+AGENT: 
+- Scanning Structure... [OK]
+- Scanning Skills... [WARNING: bug-fix/examples.md is empty]
+- Scanning Adapters... [OK]
+Health Score: 95/100
+Action: Regenerating bug-fix/examples.md...
+```
+
+## Notes
+> [!NOTE]
+> The Auditor must not modify user source code. It only targets `.agent-os/` internal framework files.

package/core/KNOWLEDGE_REGENERATOR.md

@@ -0,0 +1,30 @@
+# Knowledge Regenerator
+
+## Purpose
+To dynamically update, merge, or overwrite specific Project Knowledge templates without destroying manual user overrides or requiring a complete repository re-scan.
+
+## Responsibilities
+- Regenerate outdated knowledge identified by the `KNOWLEDGE_VALIDATOR`.
+- Safely merge new architectural findings into existing templates.
+- Update the system's global project understanding silently.
+
+## Workflow
+1. **Receive Flags**: Obtain the list of stale templates from `KNOWLEDGE_VALIDATOR.md`.
+2. **Targeted Scan**: Perform an isolated scan on the relevant modules (e.g., if Database Rules are stale, scan only the database layer).
+3. **Merge Logic**:
+   - Read the existing template.
+   - Retain custom user notes (usually marked in `> [!NOTE]` blocks).
+   - Overwrite outdated technical specifications with newly detected facts.
+4. **Commit Updates**: Save the new content into `.agent-os/project/`.
+5. **Return Control**: Hand execution back to the `SKILL_ORCHESTRATOR.md` to resume the user's original task.
+
+## Examples
+```txt
+REGENERATOR: Updating `TECH_STACK.md`...
+REGENERATOR: Merging new dependency `zustand` into State Management.
+REGENERATOR: Update complete. Returning control to Orchestrator.
+```
+
+## Notes
+> [!NOTE]
+> The Regenerator must prioritize non-destructive updates. If in doubt about a conflict, preserve the existing text and append the new findings below it.

package/core/KNOWLEDGE_VALIDATOR.md

@@ -0,0 +1,29 @@
+# Knowledge Validator
+
+## Purpose
+To ensure that existing Project Knowledge correctly reflects the active state of the repository, preventing Agent OS from hallucinating or using stale architectural context.
+
+## Responsibilities
+- Validate generated knowledge templates against actual source code files.
+- Detect stale knowledge (e.g., `TECH_STACK.md` says React, but the project is now Vue).
+- Detect missing knowledge (e.g., `DATABASE_RULES.md` says N/A, but a Prisma schema was recently added).
+
+## Workflow
+1. **Trigger**: Invoked by `AUTO_PROJECT_DETECTOR` when a major file changes, or invoked periodically by the Orchestrator.
+2. **Cross-Reference**:
+   - Compare `TECH_STACK.md` vs `package.json` or `go.mod`.
+   - Compare `ARCHITECTURE.md` vs actual folder structure.
+   - Compare `DEPENDENCY_MAP.md` vs workspace setups.
+3. **Flag Stale Elements**: Mark discrepancies.
+4. **Trigger Regeneration**: If discrepancies exceed the threshold, pass the list of flagged templates to `KNOWLEDGE_REGENERATOR.md`.
+
+## Examples
+```txt
+VALIDATOR: Checking `DATABASE_RULES.md`...
+VALIDATOR: [STALE] Database rules show N/A, but `prisma/schema.prisma` found in workspace.
+VALIDATOR: Triggering KNOWLEDGE_REGENERATOR for Database Rules.
+```
+
+## Notes
+> [!WARNING]
+> Do not invalidate custom manual rules added by developers unless they fundamentally conflict with new dependencies. Validate structural shifts, not minor text edits.

package/core/PROJECT_CONTEXT_STANDARD.md

@@ -0,0 +1,19 @@
+# PROJECT_CONTEXT_STANDARD
+
+## Purpose
+Defines the strict project context standard for Agent OS.
+
+## Responsibilities
+- Enforce standards during agent execution.
+- Provide deterministic rules for evaluation.
+
+## Workflow
+1. Load this standard before executing skill.
+2. Verify compliance during task execution.
+
+## Examples
+See `examples/` directory for concrete examples.
+
+## Notes
+> [!NOTE]
+> Always prioritize existing implementation over general assumptions.

package/core/QUALITY_GATES.md

@@ -0,0 +1,42 @@
+# QUALITY_GATES
+
+## Purpose
+Defines the mandatory executable checks that must pass before Agent OS work is reported as complete.
+
+## Responsibilities
+- Convert governance expectations into commands that can be rerun.
+- Block completion when framework structure, runtime sync, tests, or report standards fail.
+- Keep static checks local and deterministic unless an optional external scanner is explicitly configured.
+
+## Required Commands
+Run these commands before reporting a framework change as complete:
+
+1. `npm run quality`
+2. `npm run sync:runtime` when source files under `core/`, `skills/`, `templates/`, `validators/`, `hooks/`, or CLI scripts affect runtime behavior.
+3. `git diff --check`
+
+## PASS Criteria
+- `npm run quality` exits with code `0`.
+- `npm run quality:static` exits with code `0`.
+- `npm test` reports zero failed tests.
+- `npm run validate` reports `Framework validation passed`.
+- Runtime `.agent-os/` files are synchronized when runtime-facing source changes.
+- No generated report uses forbidden placeholder markers.
+
+## FAIL Criteria
+- Any required command exits non-zero.
+- A skill is missing `SKILL.md`, `workflow.md`, `checklist.md`, or `report-template.md`.
+- A report template is missing any standard section.
+- Runtime project knowledge is missing `PROJECT_PROFILE.md`, `TECH_STACK.md`, `ARCHITECTURE.md`, or `WORKSPACE_MAP.md`.
+- A completion claim is made without fresh command evidence.
+
+## Workflow
+1. Determine whether the task changes source, runtime, tests, or docs.
+2. Add or update regression tests before implementation.
+3. Run `npm run quality`.
+4. If runtime-facing files changed, run `npm run sync:runtime` and rerun `npm run quality`.
+5. Report the exact commands and outcomes.
+
+## Notes
+> [!NOTE]
+> External Sonar or hosted static-analysis services can be added later, but the local quality gate must remain runnable without network access.

package/core/REPORTING_STANDARD.md

@@ -0,0 +1,47 @@
+# REPORTING_STANDARD
+
+## Purpose
+Defines the required structure and evidence rules for Agent OS reports, exports, and notifications.
+
+## Responsibilities
+- Keep human-facing reports consistent across CLI commands and skill workflows.
+- Ensure every pass/fail claim includes evidence.
+- Prevent placeholder or unverifiable report content from being delivered.
+
+## Required Sections
+Every execution report must include:
+1. Executive Summary
+2. Scope
+3. Knowledge Confidence
+4. Knowledge Classification
+5. Traceability Matrix
+6. Evidence
+7. Root Cause
+8. Impact
+9. Recommendation
+10. Quality Gate
+11. Enterprise Readiness
+12. Final Decision
+
+## Evidence Requirements
+- Include exact command names for tests, validation, quality gates, and report notifications.
+- Include run IDs and step statuses when reporting run lifecycle outcomes.
+- Include Telegram dry-run payload path or live-send status when Telegram notification is used.
+- State `N/A. Reason: ...` only when a section is structurally required but not applicable to the task.
+
+## Final Decision
+Allowed final decisions:
+- `PASS` when implementation executed and all required gates passed.
+- `CONDITIONAL PASS` when only a validated plan or dry-run execution was produced.
+- `FAIL` when any required validation failed.
+- `BLOCKED` when the task cannot proceed without missing credentials, permissions, or user input.
+
+## Workflow
+1. Render reports from structured run data when available.
+2. Validate required sections before saving or delivering a report.
+3. Export reports through configured channels only when the channel is enabled.
+4. For Telegram, require explicit dry-run or send mode.
+
+## Notes
+> [!NOTE]
+> Reports must summarize evidence; they must not expose secrets such as Telegram bot tokens.

package/core/SKILL_ORCHESTRATOR.md

@@ -0,0 +1,63 @@
+# Skill Orchestrator V2
+
+## Purpose
+To manage the end-to-end lifecycle of an agentic task, serving as the central nervous system that seamlessly handles Auto-Onboarding, task routing, and sequential skill chaining natively.
+
+## Responsibilities
+- Intercept tasks and validate environment readiness before executing them.
+- Ensure project knowledge is fresh and present.
+- Chain skills sequentially (e.g., Fix Bug -> Audit Security -> Run E2E Tests).
+- Maintain context across skill transitions.
+- Aggregate execution reports into a single final output.
+
+## Workflow
+1. **Receive Task**: Parse the user's initial prompt.
+2. **Detect Task Type**: Route to the correct primary skill (`BUG:`, `ENHANCEMENT:`, etc.).
+3. **Validate Project Knowledge**: 
+   - Invoke `AUTO_PROJECT_DETECTOR.md` to ensure `.agent-os/project/` exists.
+   - Invoke `KNOWLEDGE_VALIDATOR.md` to ensure knowledge is not stale.
+4. **Auto-Onboard (If Required)**: If knowledge is missing or invalid, invoke `AGENT_OS_BOOTSTRAP.md` or `KNOWLEDGE_REGENERATOR.md` in the background. Do not ask the user for permission.
+5. **Execute Primary Skill**: Pass context to the required skill (e.g., `bug-fix`).
+6. **Execute Dependent Skills**: Run chained tasks (e.g., `audit` and `selenium-e2e`) passing context forward.
+7. **Produce Report**: Compile the final results into a master report.
+
+## CLI Planning
+The `agent-os orchestrate "<prompt>"` command produces a deterministic sequential execution plan without executing skills. The plan includes:
+- Detected trigger.
+- Ordered skill chain.
+- Step dependencies.
+- Validation diagnostics with `PASS` or `FAIL` status.
+- Master report section skeleton.
+
+The planner fails closed when prompts use unsupported triggers, required skills are missing from source or runtime, or dependency order is invalid. Automatic execution and parallel dispatch are separate milestones and must remain gated by dependency validation.
+
+Use `--write-report <path>` to render a master report stub from a validated plan. Report writing is blocked when validation fails.
+
+Use `--run-root <dir>` to create an execution run directory from a validated plan. The run directory contains:
+- `plan.json`
+- `steps.json`
+- `master-report.md`
+
+Use `--run-id <id>` only when a deterministic run directory name is required, such as in tests.
+
+Use `agent-os run-step --run-dir <dir> --step <number> --status <status>` to update execution state inside an existing run directory. Allowed statuses are `pending`, `running`, `passed`, `failed`, and `blocked`. A step can only move to `running` or `passed` after every dependency in `dependsOn` is already `passed`. When a step is marked `failed`, downstream dependent steps are automatically marked `blocked`. This updates `steps.json`, `plan.json`, and `master-report.md`.
+
+Use `agent-os run-status --run-dir <dir>` to summarize an execution run. The command returns total step count, counts for each state, and a derived run status of `pending`, `running`, `failed`, or `complete`.
+
+Use `agent-os run-list --run-root <dir>` to summarize every valid run directory inside a run root.
+
+## Examples
+```txt
+USER: BUG: The login page crashes. Fix it, audit the auth module, and test it.
+ORCHESTRATOR:
+1. Validating Knowledge... [Missing! Triggering Auto-Onboarding...]
+2. Auto-Onboarding... [Done]
+3. Loading `bug-fix` skill... [Done]
+4. Passing changes to `audit` skill... [Done]
+5. Passing UI changes to `selenium-e2e` skill... [Done]
+Master Report Generated.
+```
+
+## Notes
+> [!IMPORTANT]
+> If an unrecoverable failure occurs during a skill execution, the orchestrator must halt the chain immediately and inform the user.

package/core/TASK_ROUTER.md

@@ -0,0 +1,33 @@
+# TASK_ROUTER
+
+## Purpose
+Defines the strict task router for Agent OS.
+
+## Responsibilities
+- Enforce standards during agent execution.
+- Provide deterministic rules for evaluation.
+
+## Workflow
+1. Load this standard before executing skill.
+2. Verify compliance during task execution.
+
+## Strict Routing
+
+### AUDIT
+When the `AUDIT:` trigger is detected, the router MUST route through the following sequence:
+1. `COMPLIANCE_GATE`
+2. `AUTO_PROJECT_DETECTOR`
+3. `KNOWLEDGE_VALIDATOR`
+4. `SKILL_ORCHESTRATOR`
+5. `audit` skill
+6. `TRACEABILITY_STANDARD`
+7. `REPORTING_STANDARD`
+
+**Rule:** `AUDIT` must never be limited to frontend files when backend or service folders exist in `WORKSPACE_MAP.md`.
+
+## Examples
+See `examples/` directory for concrete examples.
+
+## Notes
+> [!NOTE]
+> Always prioritize existing implementation over general assumptions.

package/core/TRACEABILITY_STANDARD.md

@@ -0,0 +1,40 @@
+# TRACEABILITY_STANDARD
+
+## Purpose
+Defines the minimum traceability chain that every Agent OS task must preserve from prompt to evidence.
+
+## Responsibilities
+- Make task routing auditable.
+- Link implementation changes to validation evidence.
+- Ensure frontend, backend, service, runtime, and reporting impacts are not reviewed in isolation when a workspace map shows multiple roots.
+
+## Traceability Layers
+- **Layer 1: User Trigger** - Original prompt and detected trigger.
+- **Layer 2: Entrypoint** - `ENTRYPOINT.md` and mandatory pre-execution checklist.
+- **Layer 3: Router** - `core/TASK_ROUTER.md` trigger and ordered skill chain.
+- **Layer 4: Project Knowledge** - `.agent-os/project/` files used for context.
+- **Layer 5: Skill Contract** - Matching `skills/<skill>/SKILL.md`, `workflow.md`, and `checklist.md`.
+- **Layer 6: Source Changes** - Exact files changed.
+- **Layer 7: Runtime Sync** - `.agent-os/` runtime files affected by source changes.
+- **Layer 8: Run Lifecycle** - `plan.json`, `steps.json`, and `master-report.md` updates.
+- **Layer 9: Report Channel** - Export or notification channel used, when applicable.
+- **Layer 10: Evidence** - Test, validation, static-analysis, and notification outputs.
+
+## Required Traceability Output
+Every final report must include:
+- Trigger and skill chain.
+- Files inspected and files changed.
+- Tests and validation commands run.
+- Any skipped validation with a concrete reason.
+- Notification channel evidence when Telegram or another report channel is used.
+
+## Workflow
+1. Read the entrypoint and router.
+2. Resolve the task to a skill chain.
+3. Inspect project knowledge and impacted files.
+4. Execute changes and update run lifecycle artifacts when a run directory is used.
+5. Attach Layer 10 evidence before reporting completion.
+
+## Notes
+> [!NOTE]
+> If `WORKSPACE_MAP.md` lists frontend and backend or service roots, audits and enhancements must account for cross-root impact.

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@adityaaria/agent-os",
+  "version": "1.0.0",
+  "description": "Portable Agent OS for skill-based coding workflows across IDEs and projects.",
+  "type": "module",
+  "files": [
+    "bin",
+    "scripts",
+    "core",
+    "skills",
+    "templates",
+    "adapters",
+    "AGENTS.md",
+    "ENTRYPOINT.md",
+    "AGENT_OS_BOOTSTRAP.md"
+  ],
+  "bin": {
+    "agent-os": "bin/agent-os.mjs"
+  },
+  "scripts": {
+    "test": "node --test",
+    "validate": "node scripts/validate-framework.mjs",
+    "quality": "npm run quality:static && npm test && npm run validate",
+    "quality:static": "node scripts/quality-static.mjs",
+    "sync:runtime": "node scripts/sync-runtime.mjs",
+    "setup": "node scripts/setup-wizard.mjs"
+  }
+}