ace-pack 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandr Dudka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,242 @@
+<p align="center">
+  <img src="./logo.svg" alt="ACE Pack logo" width="72" height="72" />
+</p>
+
+<h1 align="center">ACE Pack</h1>
+
+[![npm version](https://img.shields.io/npm/v/ace-pack?color=0f766e)](https://www.npmjs.com/package/ace-pack)
+[![zero dependencies](https://img.shields.io/badge/runtime-zero_dependencies-111827)](#)
+[![license](https://img.shields.io/badge/license-MIT-2563eb)](#)
+
+**The zero-dependency cognitive architecture framework for AI-driven development.**
+
+ACE (Agentic Context Engine) gives AI coding agents a deterministic memory
+layer, repository-aware risk rules, and repeatable quality gates using plain
+Markdown and native Node.js scripts.
+
+AI agents are brilliant, but stateless by default. ACE gives them the project
+memory, guardrails, and closeout discipline they need to behave like reliable
+engineering teammates inside real repositories.
+
+## Why ACE Exists
+
+AI-assisted development has a new set of failure modes that ordinary chat does
+not solve:
+
+- **Context Amnesia** - the agent forgets last week's architecture decisions
+  and suggests reworking settled systems.
+- **Architectural Drift** - the agent invents new patterns, libraries, or
+  boundaries because the project rules are not loaded every time.
+- **Security Blind Spots** - auth, tokens, private data, migrations, and
+  environment isolation look like ordinary code unless they are marked as
+  high-risk.
+- **Prompt Fatigue** - humans waste time collecting files, repeating rules, and
+  reminding the agent to validate, document, and hand off its work.
+
+ACE turns those soft expectations into local project structure:
+
+- `.ai/*` Markdown files keep task state, decisions, handoffs, and reflection
+  readable by any LLM.
+- `AGENTS.md` keeps stack, architecture, and workflow rules close to the code.
+- `.ai/memory-config.json` marks high-risk paths and keywords for the current
+  repository.
+- `ace:validate` stays project-owned so every repo can define its real
+  mechanical quality gate.
+
+## ACE vs. Just Chatting With AI
+
+A chat session is a smart one-off conversation. ACE is a governed agent
+workflow.
+
+With ordinary chat, the developer carries the discipline: gather context, repeat
+rules, ask for alternatives, remember security constraints, run checks, and
+write handoff notes.
+
+With ACE, the repository carries the discipline:
+
+- `ace:classify` detects whether the change is small, standard, or large.
+- Large and high-risk work starts with a shift-left design review before code.
+- `ace:hub` generates focused context instead of manual copy/paste bundles.
+- `ace:finish` commits decisions, changed files, validation notes, and
+  reflection back into project memory.
+
+ACE is not a prompt library. It is cognitive architecture for managing AI
+coding agents inside real repositories.
+
+## What ACE Boosts
+
+**For the AI agent**
+
+- Context packing that points the model at the right files first.
+- Strict guardrails for high-risk code paths and keywords.
+- Stateful reflection so repeated mistakes become visible project memory.
+- A universal Markdown format readable by GPT, Claude, Cursor, Aider, and other
+  coding agents.
+
+**For the human developer**
+
+- Automated review prompts and closeout discipline.
+- Self-documenting architecture and decision history.
+- Zero framework lock-in and no runtime dependencies.
+- Less boilerplate in every agent session.
+
+## How It Works
+
+```text
+Classify Risk -> Shift-Left Design Review -> Write Code -> Validate -> Commit to Memory
+```
+
+ACE is intentionally boring technology: standard Markdown in `.ai/`, standard
+`package.json` scripts, and native Node.js.
+
+The key behavior is **Shift-Left Design Review**. For large or high-risk tasks,
+the agent must stop before implementation, fill `.ai/current-task.md` with the
+business value and technical approach, compare viable patterns, and choose one
+explicitly. The code comes after the architectural decision, not before it.
+
+Unknown repositories start with a neutral memory config. Then `ace:onboard`
+profiles the repo and recommends project-specific risk rules before they are
+applied.
+
+## Quick Start
+
+Install ACE into the current repository:
+
+```bash
+pnpm dlx ace-pack init
+```
+
+Or with npm:
+
+```bash
+npx ace-pack init
+```
+
+Install into another repository:
+
+```bash
+pnpm dlx ace-pack init ./my-project
+```
+
+Profile the project:
+
+```bash
+pnpm ace:onboard
+pnpm ace:onboard -- --apply
+```
+
+For Python, Go, Rust, .NET, or any repo without `package.json`, ACE creates a
+lightweight private runner package:
+
+```json
+{
+  "description": "Auto-generated lightweight runner for ACE (Agentic Context Engine) scripts. No node_modules required."
+}
+```
+
+No dependency install is required for ACE itself. The runner only exposes
+commands such as `ace:onboard`, `ace:hub`, `ace:classify`, and `ace:finish`.
+
+Known SaaS monorepo? Apply the built-in preset:
+
+```bash
+pnpm ace:onboard -- --preset next-trpc-drizzle-saas --apply
+```
+
+Legacy entry points remain available:
+
+```bash
+pnpm dlx agent-memory-pack ./my-project
+```
+
+## Multi-Language Examples
+
+### Next.js + tRPC + Drizzle
+
+ACE detects signals such as `next.config.ts`, `@trpc/server`, `drizzle-orm`,
+`middleware.ts`, `packages/api/src/routers/**`, and
+`packages/db/src/schema/**`. These become high-risk rules so auth, middleware,
+routers, and migrations get stricter review before code changes.
+
+```bash
+pnpm ace:onboard -- --preset next-trpc-drizzle-saas --apply
+pnpm ace:classify
+pnpm ace:validate
+pnpm ace:finish
+```
+
+### Python FastAPI
+
+ACE detects `requirements.txt`, `pyproject.toml`, `fastapi`,
+`app/core/security.py`, `app/**/auth*.py`, `app/api/**`, and `alembic/**`. The
+active project can keep using Poetry, uv, pytest, ruff, or any other Python
+tooling; ACE only provides the agent memory and workflow layer.
+
+```bash
+pnpm dlx ace-pack init
+pnpm ace:onboard -- --apply
+pnpm ace:hub
+```
+
+### Go Microservice
+
+ACE detects `go.mod`, `internal/auth/**`, `internal/middleware/**`,
+`internal/handlers/**`, and `migrations/**`. It gives AI agents the same memory
+and risk workflow without changing the Go build pipeline.
+
+```bash
+pnpm dlx ace-pack init
+pnpm ace:onboard -- --apply
+pnpm ace:classify
+```
+
+## CLI Reference
+
+| Command | Purpose |
+| --- | --- |
+| `ace:onboard` | Smart repository profiling. Writes `.ai/project-profile.md` and `.ai/memory-config.recommended.json` without changing active config. |
+| `ace:onboard -- --apply` | Merges recommendations into `.ai/memory-config.json` and marks the repo as profiled. |
+| `ace:onboard -- --preset next-trpc-drizzle-saas --apply` | Applies the built-in Next.js + tRPC + Drizzle SaaS profile. |
+| `ace:onboard -- --check` | Fails if the repository is still unprofiled. |
+| `ace:classify` | Git diff risk analysis for small, standard, and large tasks. |
+| `ace:validate` | Project-owned mechanical quality gate. ACE never overwrites this script. |
+| `ace:finish` | Adaptive closeout, memory documentation, reports, and reflection. |
+| `ace:hub` | Interactive context generator for copying focused project context into AI tools. |
+
+## Installed Project Files
+
+ACE installs or updates:
+
+- `AGENTS.md` workflow section
+- `CLAUDE.md`
+- `.ai/current-task.md`
+- `.ai/session-handoff.md`
+- `.ai/decisions.md`
+- `.ai/changed-files.md`
+- `.ai/work-log.md`
+- `.ai/reflection-log.md`
+- `.ai/product-roadmap.md`
+- `.ai/tech-docs.md`
+- `.ai/memory-config.json`
+- `.ai/archive/.gitkeep`
+- `.ai/archive/tasks/.gitkeep`
+- `scripts/*` managed ACE automation
+
+Existing memory files are not overwritten. Existing `package.json` files are
+preserved and updated idempotently.
+
+## Development
+
+```bash
+git clone https://github.com/alex-boom/ace-pack.git
+cd ace-pack
+pnpm install
+pnpm test
+```
+
+Optional local link:
+
+```bash
+pnpm link --global
+ace-pack init ./target-project
+```

package/ace-pack.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0install-ace-pack.mjs" %*

package/agent-memory-pack.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0install-ace-pack.mjs" %*

package/install-ace-pack.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0install-ace-pack.mjs" %*

package/install-ace-pack.mjs

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+import { copyFile, mkdir, readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { ensureAgentMemory } from './scripts/agent-memory-lib.mjs'
+
+const REQUIRED_PACKAGE_SCRIPTS = {
+  'ace:init': 'node ./scripts/bootstrap-agent-memory.mjs',
+  'ace:check': 'node ./scripts/check-agent-memory.mjs',
+  'ace:classify': 'node ./scripts/ai-task-classify.mjs',
+  'ace:finish': 'node ./scripts/ai-task-finish.mjs',
+  'ace:hub': 'node ./scripts/ace-hub.mjs',
+  'ace:onboard': 'node ./scripts/ace-onboard.mjs',
+  'ace:report': 'node ./scripts/ai-report.mjs',
+  'ace:report:brief': 'node ./scripts/ai-report-brief.mjs',
+  'agent-memory:init': 'node ./scripts/bootstrap-agent-memory.mjs',
+  'agent-memory:check': 'node ./scripts/check-agent-memory.mjs',
+  'ai:project:onboard': 'node ./scripts/ace-onboard.mjs',
+  'ai:report': 'node ./scripts/ai-report.mjs',
+  'ai:report:brief': 'node ./scripts/ai-report-brief.mjs',
+  'ai:report:currentTaskCode': 'node ./scripts/ai-report-current-task-code.mjs',
+  'ai:task:classify': 'node ./scripts/ai-task-classify.mjs',
+  'ai:task:finish': 'node ./scripts/ai-task-finish.mjs',
+  'ai:update:task': 'node ./scripts/ai-update.mjs task',
+  'ai:update:handoff': 'node ./scripts/ai-update.mjs handoff',
+  'ai:update:log': 'node ./scripts/ai-update.mjs log',
+  'ai:update:decision': 'node ./scripts/ai-update.mjs decision',
+  'ai:update:changed': 'node ./scripts/ai-update.mjs changed',
+}
+
+const MANAGED_SCRIPT_FILES = [
+  'ace-hub.mjs',
+  'ace-onboard.mjs',
+  'ace-project-presets.mjs',
+  'ace-universal-doc-templates.mjs',
+  'agent-memory-lib.mjs',
+  'agent-memory-templates.mjs',
+  'ai-memory-config.mjs',
+  'ai-memory-utils.mjs',
+  'ai-report-brief.mjs',
+  'ai-report-current-task-code.mjs',
+  'ai-report.mjs',
+  'ai-task-classify.mjs',
+  'ai-task-finish.mjs',
+  'ai-update.mjs',
+  'bootstrap-agent-memory.mjs',
+  'check-agent-memory.mjs',
+]
+
+const defaultAgentsTemplate = `# AGENTS.md
+
+Repository rules for AI coding agents working in this project.
+
+## Project Rules
+
+- Add project-specific stack, architecture, and workflow rules here.
+`
+
+const currentFilePath = fileURLToPath(import.meta.url)
+const currentScriptDir = path.join(path.dirname(currentFilePath), 'scripts')
+const RUNNER_PACKAGE_DESCRIPTION =
+  'Auto-generated lightweight runner for ACE (Agentic Context Engine) scripts. No node_modules required.'
+
+function normalizeTrailingNewline(content) {
+  return content.endsWith('\n') ? content : `${content}\n`
+}
+
+async function readTextIfExists(filePath) {
+  try {
+    return await readFile(filePath, 'utf8')
+  } catch (error) {
+    if (error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT') {
+      return null
+    }
+
+    throw error
+  }
+}
+
+async function ensureDefaultAgentsFile(rootDir) {
+  const agentsPath = path.join(rootDir, 'AGENTS.md')
+  const existingContent = await readTextIfExists(agentsPath)
+
+  if (existingContent !== null) {
+    return { created: false, path: 'AGENTS.md' }
+  }
+
+  await writeFile(agentsPath, normalizeTrailingNewline(defaultAgentsTemplate), 'utf8')
+  return { created: true, path: 'AGENTS.md' }
+}
+
+async function syncManagedScripts(rootDir) {
+  const createdFiles = []
+  const updatedFiles = []
+  const targetScriptDir = path.join(rootDir, 'scripts')
+
+  await mkdir(targetScriptDir, { recursive: true })
+
+  for (const filename of MANAGED_SCRIPT_FILES) {
+    const sourcePath = path.join(currentScriptDir, filename)
+    const targetPath = path.join(targetScriptDir, filename)
+    const sourceContent = await readFile(sourcePath, 'utf8')
+    const targetContent = await readTextIfExists(targetPath)
+
+    if (targetContent === sourceContent) {
+      continue
+    }
+
+    await copyFile(sourcePath, targetPath)
+
+    if (targetContent === null) {
+      createdFiles.push(`scripts/${filename}`)
+    } else {
+      updatedFiles.push(`scripts/${filename}`)
+    }
+  }
+
+  return { createdFiles, updatedFiles }
+}
+
+async function ensurePackageScripts(rootDir) {
+  const { packageJson, packageJsonPath } = await ensurePackageJson(rootDir)
+  const nextScripts = {
+    ...(packageJson.scripts ?? {}),
+  }
+  let changed = false
+
+  for (const [scriptName, scriptValue] of Object.entries(REQUIRED_PACKAGE_SCRIPTS)) {
+    if (nextScripts[scriptName] === scriptValue) {
+      continue
+    }
+
+    nextScripts[scriptName] = scriptValue
+    changed = true
+  }
+
+  if (!changed) {
+    return false
+  }
+
+  await writeFile(
+    packageJsonPath,
+    `${JSON.stringify({ ...packageJson, scripts: nextScripts }, null, 2)}\n`,
+    'utf8',
+  )
+
+  return true
+}
+
+function buildPackageName(rootDir) {
+  const folderName = path.basename(rootDir).toLowerCase()
+  const packageName = folderName
+    .replace(/[^a-z0-9._-]+/g, '-')
+    .replace(/^[._-]+|[._-]+$/g, '')
+
+  return packageName || 'ace-project'
+}
+
+async function ensurePackageJson(rootDir) {
+  const packageJsonPath = path.join(rootDir, 'package.json')
+  const packageJsonContent = await readTextIfExists(packageJsonPath)
+
+  if (packageJsonContent !== null) {
+    return {
+      created: false,
+      packageJson: JSON.parse(stripByteOrderMark(packageJsonContent)),
+      packageJsonPath,
+    }
+  }
+
+  const packageJson = {
+    name: buildPackageName(rootDir),
+    private: true,
+    description: RUNNER_PACKAGE_DESCRIPTION,
+    scripts: {},
+  }
+
+  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, 'utf8')
+
+  return {
+    created: true,
+    packageJson,
+    packageJsonPath,
+  }
+}
+
+function stripByteOrderMark(content) {
+  return content.replace(/^\uFEFF/u, '')
+}
+
+export async function installAcePack(targetDir) {
+  const normalizedTargetDir = path.resolve(targetDir)
+  const createdFiles = []
+  const updatedFiles = []
+
+  const packageResult = await ensurePackageJson(normalizedTargetDir)
+
+  if (packageResult.created) {
+    createdFiles.push('package.json')
+  }
+
+  const agentsResult = await ensureDefaultAgentsFile(normalizedTargetDir)
+
+  if (agentsResult.created) {
+    createdFiles.push(agentsResult.path)
+  }
+
+  const scriptResult = await syncManagedScripts(normalizedTargetDir)
+  createdFiles.push(...scriptResult.createdFiles)
+  updatedFiles.push(...scriptResult.updatedFiles)
+
+  if (await ensurePackageScripts(normalizedTargetDir)) {
+    updatedFiles.push('package.json')
+  }
+
+  const memoryResult = await ensureAgentMemory(normalizedTargetDir)
+  createdFiles.push(...memoryResult.createdFiles)
+  updatedFiles.push(...memoryResult.updatedFiles)
+
+  return {
+    createdFiles,
+    targetDir: normalizedTargetDir,
+    updatedFiles,
+  }
+}
+
+export function resolveTargetDir(args, cwd = process.cwd()) {
+  const [commandOrTarget, maybeTarget] = args
+
+  if (commandOrTarget === 'init') {
+    return maybeTarget ? path.resolve(cwd, maybeTarget) : cwd
+  }
+
+  return commandOrTarget ? path.resolve(cwd, commandOrTarget) : cwd
+}
+
+export function printInstallResult(result) {
+  if (result.updatedFiles.length === 0 && result.createdFiles.length === 0) {
+    process.stderr.write(`ACE pack is already up to date in ${result.targetDir}\n`)
+  }
+
+  if (result.updatedFiles.length > 0) {
+    process.stderr.write(`Updated: ${result.updatedFiles.join(', ')}\n`)
+  }
+
+  if (result.createdFiles.length > 0) {
+    process.stderr.write(`Created: ${result.createdFiles.join(', ')}\n`)
+  }
+
+  process.stderr.write('Next: run pnpm.cmd ace:onboard\n')
+}
+
+const isMainModule =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === currentFilePath
+
+if (isMainModule) {
+  const targetDir = resolveTargetDir(process.argv.slice(2))
+  const result = await installAcePack(targetDir)
+  printInstallResult(result)
+}

package/install-agent-memory-pack.cmd

@@ -0,0 +1,2 @@
+@echo off
+node "%~dp0install-ace-pack.mjs" %*

package/install-agent-memory-pack.mjs

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import { installAcePack, printInstallResult, resolveTargetDir } from './install-ace-pack.mjs'
+
+export const installAgentMemoryPack = installAcePack
+
+const currentFilePath = fileURLToPath(import.meta.url)
+const isMainModule =
+  process.argv[1] !== undefined && path.resolve(process.argv[1]) === currentFilePath
+
+if (isMainModule) {
+  const targetDir = resolveTargetDir(process.argv.slice(2))
+  const result = await installAcePack(targetDir)
+  printInstallResult(result)
+}

package/logo.svg

@@ -0,0 +1,25 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32" role="img" aria-labelledby="ace-pack-logo-title">
+  <title id="ace-pack-logo-title">ACE Pack</title>
+  <style>
+    .icon-dark-part {
+      fill: #0f172a;
+    }
+    .icon-pink-part {
+      fill: #db2777;
+    }
+    @media (prefers-color-scheme: dark) {
+      .icon-dark-part {
+        fill: #f8fafc;
+      }
+    }
+  </style>
+  <rect class="icon-dark-part" x="15.2" y="7.3" width="1.6" height="5.3" rx="0.8" />
+  <rect class="icon-dark-part" x="15.2" y="19.4" width="1.6" height="5.3" rx="0.8" />
+  <rect class="icon-dark-part" x="7.3" y="15.2" width="5.3" height="1.6" rx="0.8" />
+  <rect class="icon-dark-part" x="19.4" y="15.2" width="5.3" height="1.6" rx="0.8" />
+  <rect class="icon-dark-part" x="12.4" y="1.6" width="7.2" height="7.2" rx="1.6" />
+  <rect class="icon-dark-part" x="12.4" y="23.2" width="7.2" height="7.2" rx="1.6" />
+  <rect class="icon-dark-part" x="1.6" y="12.4" width="7.2" height="7.2" rx="1.6" />
+  <rect class="icon-dark-part" x="23.2" y="12.4" width="7.2" height="7.2" rx="1.6" />
+  <circle class="icon-pink-part" cx="16" cy="16" r="4.45" />
+</svg>

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "ace-pack",
+  "version": "0.1.0",
+  "description": "Zero-dependency cognitive architecture framework for AI-driven development.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alexandr Dudka <dudka.alexandr83@gmail.com>",
+  "homepage": "https://github.com/alex-boom/ace-pack#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alex-boom/ace-pack.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alex-boom/ace-pack/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "llm",
+    "codex",
+    "agentic",
+    "workflow",
+    "development"
+  ],
+  "files": [
+    "README.md",
+    "logo.svg",
+    "*.cmd",
+    "*.mjs",
+    "scripts/*.mjs"
+  ],
+  "bin": {
+    "ace-pack": "install-ace-pack.mjs",
+    "agent-memory-pack": "install-agent-memory-pack.mjs"
+  },
+  "scripts": {
+    "install:pack": "node ./install-ace-pack.mjs",
+    "install:legacy": "node ./install-agent-memory-pack.mjs",
+    "link:global": "pnpm link --global",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.4"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}