kracked-core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KrackedDevs
+
+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,146 @@
+<div align="center">
+
+# Kracked Core
+
+**Your AI coding agent forgets everything between sessions — and builds whatever you vaguely described.**
+
+Kracked Core fixes both.
+
+[![npm](https://img.shields.io/npm/v/kracked-core?color=black)](https://www.npmjs.com/package/kracked-core)
+[![license](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
+
+```bash
+npx kracked-core init
+```
+
+</div>
+
+---
+
+## The problem
+
+You've had this conversation:
+
+> **You:** Build me a login page.
+> **Agent:** *builds a login page*
+> **You:** No, we use Supabase auth. I told you yesterday.
+> **Agent:** You're absolutely right! Let me fix that.
+
+Tomorrow it happens again. Your agent has no memory. Every session starts from zero, and every session you re-explain your stack, your conventions, and the same three mistakes you already corrected.
+
+The second problem is quieter: you describe a feature in one sentence, the agent builds *something*, and you spend the next hour discovering it wasn't what you meant.
+
+## What this gives you
+
+| | Before | After |
+|---|---|---|
+| **Memory** | Re-explain everything, every session | Agent reads its memory on boot and picks up where you left off |
+| **Mistakes** | Same correction, over and over | Corrections get written down once, and stay corrected |
+| **Building** | "Build me X" → surprise | Idea → spec → build → review, with a tracker you can see |
+| **"Done"** | Agent says done, it isn't | Nothing is `done` without stated evidence |
+
+It's plain markdown files. You can read them, edit them, commit them to git, and delete them. No database, no cloud, no black box.
+
+## Install
+
+```bash
+npx kracked-core init
+```
+
+The wizard asks a few questions — name your agent, is this a new or existing project, which editor you use — and writes the files. Hold Enter through it and you'll get a sane setup.
+
+**Works with:** Antigravity · Claude Code · Cursor · Windsurf · anything that reads `AGENTS.md`
+
+## Use
+
+Three commands. That's the whole thing.
+
+```
+/kracked-boot    Start of session — agent loads its memory and tells you where you left off
+/kracked-sdd     Build something — idea → spec → docs → build → review
+/kracked-wrap    End of session — agent writes down what it learned
+```
+
+> **`/kracked-wrap` is not optional.** Boot without wrap is a memory system that just forgets more slowly. The wrap is where memory actually gets written.
+
+## How it works
+
+Two layers of memory, and the split between them is the whole idea.
+
+```
+~/.kracked/              GLOBAL — survives every project
+  identity.md            who your agent is
+  preferences.md         how you like to work
+  lessons.md             mistakes it won't repeat  ← read every boot
+  lessons-archive.md     the full detail           ← read on demand only
+  projects.md            which projects exist
+
+your-project/.kracked/   PROJECT — this codebase only
+  project.md             stack, conventions, how to run it
+  session.md             where we are right now
+  decisions.md           why things are the way they are
+  sdd/tracker.md         story status + evidence
+```
+
+### The boundary rule
+
+| Goes GLOBAL | Goes PROJECT |
+|---|---|
+| Who your agent is | What this codebase is |
+| How you like to work | This project's conventions |
+| Lessons that apply anywhere | This sprint's state |
+
+Getting this wrong is the #1 failure mode. Put "we use Tailwind in this repo" into global memory and your agent will try to use Tailwind in your Python API. Keep project truth in the project.
+
+### Why lessons split into two files
+
+`lessons.md` is read on **every single boot**. If it grew forever, boot would get slower forever — and Antigravity caps rules files at 12,000 characters, so eventually it would simply break.
+
+So: the full lesson goes into `lessons-archive.md`, and **one line** goes into `lessons.md`. The index stays small. The archive grows without cost, and gets opened only when a specific lesson is actually relevant.
+
+Your boot payload stays flat no matter how much your agent learns. That's the trick.
+
+## The build flow
+
+`/kracked-sdd` doesn't force ceremony on everything. It sizes the job first:
+
+| Job | What happens |
+|---|---|
+| Fix a typo | Skips straight to the fix. No spec. |
+| Small, clear feature | Light spec → build → review |
+| Big or risky | Full flow: idea → spec → stories → build → review |
+
+Then it tracks the work:
+
+| ID | Story | Status | Evidence |
+|---|---|---|---|
+| 1.1 | User can log in | done | manual login OK, 3 tests pass |
+| 1.2 | Password reset | in-progress | — |
+| 1.3 | Remember me | backlog | — |
+
+**A story cannot move to `done` without evidence.** Not "the tests pass" — what did you actually verify, and what did you *not*? Green tests are not a working feature. This one rule catches more bugs than any other part of the system.
+
+## FAQ
+
+**Does this send my code anywhere?**
+No. Everything is local markdown files. There's no service, no telemetry, no account.
+
+**Should I commit `.kracked/` to git?**
+Yes, mostly. Project memory is useful to your teammates. Add `.kracked/session.md` to `.gitignore` if you don't want your working state shared.
+
+**My editor isn't listed. Will it work?**
+If it reads `AGENTS.md`, yes. That's most of them now. Claude Code is the exception — it reads `CLAUDE.md`, so we write a one-line shim that imports `AGENTS.md`.
+
+**Can I edit the memory files by hand?**
+Please do. They're yours. Correcting your agent's memory directly is faster than arguing with it.
+
+**How is this different from just writing a good prompt?**
+A prompt lasts one session. This lasts across all of them, and it compounds — every mistake you correct is a mistake you never see again.
+
+## Contributing
+
+Issues and PRs welcome. This started as teaching material for the [KrackedDevs](https://github.com/Krackeddevs-Org) weekly class, so clarity for beginners beats cleverness.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/kracked-core.mjs

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+import { runInit } from '../src/wizard.mjs';
+
+const USAGE = `kracked-core — memory & workflow installer for AI coding agents
+
+Usage:
+  npx kracked-core init     Set up global + project memory
+
+Options:
+  -h, --help                 Show this help
+`;
+
+async function main() {
+  const [, , subcommand] = process.argv;
+
+  if (subcommand === 'init') {
+    await runInit();
+    return;
+  }
+
+  if (subcommand === '--help' || subcommand === '-h' || !subcommand) {
+    process.stdout.write(USAGE);
+    process.exit(subcommand ? 0 : 1);
+    return;
+  }
+
+  process.stderr.write(`Unknown command: ${subcommand}\n\n${USAGE}`);
+  process.exit(1);
+}
+
+main().catch((err) => {
+  process.stderr.write(`\nkracked-core failed: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "kracked-core",
+  "version": "1.0.0",
+  "description": "Zero-dependency memory & workflow installer for AI coding agents — global identity, project memory, and skills that survive session restarts.",
+  "type": "module",
+  "bin": {
+    "kracked-core": "./bin/kracked-core.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Krackeddevs-Org/kracked-core.git"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "memory",
+    "cli",
+    "claude",
+    "antigravity"
+  ]
+}

package/src/detect.mjs

@@ -0,0 +1,106 @@
+// Detection helpers: what's already on disk, so the wizard doesn't ask
+// questions it can answer itself and scaffold.mjs doesn't clobber anything.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/** Does ~/.kracked/ already exist? */
+export function globalMemoryExists() {
+  const dir = path.join(os.homedir(), '.kracked');
+  return fs.existsSync(dir) && fs.statSync(dir).isDirectory();
+}
+
+export function globalMemoryDir() {
+  return path.join(os.homedir(), '.kracked');
+}
+
+/**
+ * Is the target dir an existing codebase, empty, or new (doesn't exist yet)?
+ * Returns one of: "new" (doesn't exist), "empty" (exists, no entries),
+ * "existing" (exists, has files/dirs signalling a real codebase).
+ */
+export function classifyProjectDir(targetDir) {
+  if (!fs.existsSync(targetDir)) return 'new';
+
+  const entries = fs.readdirSync(targetDir).filter((e) => e !== '.DS_Store');
+  if (entries.length === 0) return 'empty';
+  return 'existing';
+}
+
+// Markers checked, in order, to guess the primary stack of an existing repo.
+const STACK_MARKERS = [
+  { file: 'package.json', label: 'Node.js' },
+  { file: 'requirements.txt', label: 'Python' },
+  { file: 'pyproject.toml', label: 'Python' },
+  { file: 'go.mod', label: 'Go' },
+  { file: 'composer.json', label: 'PHP' },
+  { file: 'Cargo.toml', label: 'Rust' },
+  { file: 'Gemfile', label: 'Ruby' },
+  { file: 'pom.xml', label: 'Java (Maven)' },
+  { file: 'build.gradle', label: 'Java/Kotlin (Gradle)' },
+  { file: 'mix.exs', label: 'Elixir' },
+];
+
+/**
+ * Extract a light summary of an existing codebase: name, stack guess,
+ * framework hints, package.json scripts, whether it's a git repo.
+ * Never throws — worst case it returns a mostly-empty summary.
+ */
+export function scanExistingProject(targetDir) {
+  const summary = {
+    name: path.basename(path.resolve(targetDir)),
+    stack: [],
+    frameworks: [],
+    scripts: {},
+    isGitRepo: fs.existsSync(path.join(targetDir, '.git')),
+  };
+
+  for (const marker of STACK_MARKERS) {
+    if (fs.existsSync(path.join(targetDir, marker.file))) {
+      summary.stack.push(marker.label);
+    }
+  }
+
+  const pkgPath = path.join(targetDir, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if (pkg.name) summary.name = pkg.name;
+      if (pkg.scripts && typeof pkg.scripts === 'object') {
+        summary.scripts = pkg.scripts;
+      }
+      const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+      const frameworkHints = [
+        'react', 'next', 'vue', 'nuxt', 'svelte', 'angular',
+        'express', 'fastify', 'nestjs', '@nestjs/core', 'koa',
+      ];
+      for (const hint of frameworkHints) {
+        if (deps && deps[hint]) summary.frameworks.push(hint);
+      }
+    } catch {
+      // Malformed package.json — skip framework/script detection, keep the rest.
+    }
+  }
+
+  return summary;
+}
+
+/** Build the {{STACK}} token value from a scan result. */
+export function stackSummaryLine(summary) {
+  const parts = [];
+  if (summary.stack.length) parts.push(summary.stack.join(', '));
+  if (summary.frameworks.length) parts.push(`(${summary.frameworks.join(', ')})`);
+  return parts.length ? parts.join(' ') : 'unknown — not auto-detected';
+}
+
+/** Which harnesses already have a footprint in this project dir? */
+export function detectHarnesses(targetDir) {
+  return {
+    claudeCode: fs.existsSync(path.join(targetDir, '.claude')) ||
+      fs.existsSync(path.join(targetDir, 'CLAUDE.md')),
+    antigravity: fs.existsSync(path.join(targetDir, '.agents')) ||
+      fs.existsSync(path.join(targetDir, 'AGENTS.md')),
+    cursor: fs.existsSync(path.join(targetDir, '.cursor')),
+  };
+}

package/src/scaffold.mjs

@@ -0,0 +1,192 @@
+// File writer: copies templates to their destinations, replacing {{TOKEN}}
+// placeholders, and never overwrites an existing file without asking first.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATES_ROOT = path.join(__dirname, '..', 'templates');
+
+const SKILL_NAMES = ['kracked-boot', 'kracked-sdd', 'kracked-wrap', 'kracked-explain'];
+
+/** Read a template file, throwing a clear error if Track A hasn't shipped it yet. */
+function readTemplate(relPath) {
+  const fullPath = path.join(TEMPLATES_ROOT, relPath);
+  if (!fs.existsSync(fullPath)) {
+    throw new Error(
+      `Missing template: templates/${relPath}\n` +
+      `This file is expected by the build contract but isn't in the package yet.`
+    );
+  }
+  return fs.readFileSync(fullPath, 'utf8');
+}
+
+/** Replace every {{TOKEN}} in content with its value from the tokens map. */
+function applyTokens(content, tokens) {
+  return content.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    return Object.prototype.hasOwnProperty.call(tokens, key) ? tokens[key] : match;
+  });
+}
+
+/**
+ * Decide what to do about a file that may already exist.
+ * Returns 'skip' | 'overwrite' | 'alongside'. Delegates the actual
+ * question to `ask` (injected so this module has no direct readline dependency).
+ */
+async function resolveConflict(destPath, ask) {
+  if (!fs.existsSync(destPath)) return 'write';
+  const choice = await ask(destPath);
+  return choice; // 'skip' | 'overwrite' | 'alongside'
+}
+
+/** Write content to destPath, honoring the conflict resolution. */
+async function writeFileWithConflictCheck(destPath, content, ask, report) {
+  const action = await resolveConflict(destPath, ask);
+
+  if (action === 'skip') {
+    report({ path: destPath, action: 'skipped (already existed)' });
+    return;
+  }
+
+  let finalPath = destPath;
+  if (action === 'alongside') {
+    finalPath = `${destPath}.kracked-new`;
+  }
+
+  fs.mkdirSync(path.dirname(finalPath), { recursive: true });
+  fs.writeFileSync(finalPath, content, 'utf8');
+  report({
+    path: finalPath,
+    action: action === 'alongside' ? 'written alongside existing file' : 'written',
+  });
+}
+
+/**
+ * Write global memory files to ~/.kracked/.
+ * `ask(destPath)` is called only when a file already exists; must resolve to
+ * 'skip' | 'overwrite' | 'alongside'.
+ * `report(entry)` is called once per file, for the wizard's final summary.
+ */
+export async function writeGlobalMemory({ tokens, ask, report }) {
+  const globalDir = path.join(os.homedir(), '.kracked');
+  // projects.md is excluded here — it's a running registry appended to by
+  // every install, never treated as a skip/overwrite conflict. See registerProject().
+  const files = ['identity.md', 'preferences.md', 'lessons.md', 'lessons-archive.md'];
+
+  for (const file of files) {
+    const destPath = path.join(globalDir, file);
+    const content = applyTokens(readTemplate(`global/${file}`), tokens);
+    await writeFileWithConflictCheck(destPath, content, ask, report);
+  }
+}
+
+/**
+ * Register this project in ~/.kracked/projects.md — create the file from its
+ * template on first use, then append one registry line per project.
+ */
+export function registerProject({ tokens }) {
+  const globalDir = path.join(os.homedir(), '.kracked');
+  const projectsPath = path.join(globalDir, 'projects.md');
+  const stack = tokens.STACK && tokens.STACK.trim() ? tokens.STACK : '—';
+  const row = `| ${tokens.PROJECT_NAME} | ${tokens.PROJECT_PATH} | ${stack} | active |`;
+
+  fs.mkdirSync(globalDir, { recursive: true });
+
+  let content;
+  if (fs.existsSync(projectsPath)) {
+    content = fs.readFileSync(projectsPath, 'utf8');
+  } else {
+    // First install: start from the template, minus its illustrative example rows.
+    content = applyTokens(readTemplate('global/projects.md'), tokens)
+      .split('\n')
+      .filter((line) => !/^\|\s*(todo-app|my-blog)\s*\|/.test(line))
+      .join('\n');
+  }
+
+  // Already registered? Leave it alone — re-running init must not duplicate rows.
+  if (content.includes(`| ${tokens.PROJECT_PATH} |`)) return;
+
+  const lines = content.split('\n');
+  const isDivider = (l) => /^\|[\s|:-]+\|?\s*$/.test(l);
+
+  // Find the table's divider row (|---|---|), then insert after the last data
+  // row that follows it. Anchoring on the divider matters: without it, a table
+  // whose only row is the header inserts ABOVE the divider and breaks the table.
+  const dividerIdx = lines.findIndex(isDivider);
+
+  if (dividerIdx >= 0) {
+    let insertAt = dividerIdx;
+    for (let i = dividerIdx + 1; i < lines.length; i++) {
+      if (/^\|/.test(lines[i])) insertAt = i;
+      else if (lines[i].trim() !== '') break;
+    }
+    lines.splice(insertAt + 1, 0, row);
+    content = lines.join('\n');
+  } else {
+    content = `${content.replace(/\s*$/, '\n')}${row}\n`;
+  }
+
+  fs.writeFileSync(projectsPath, content.replace(/\s*$/, '\n'), 'utf8');
+}
+
+/** Write project memory files to <project>/.kracked/. */
+export async function writeProjectMemory({ projectDir, tokens, ask, report }) {
+  const krackedDir = path.join(projectDir, '.kracked');
+  const files = ['project.md', 'session.md', 'decisions.md'];
+
+  for (const file of files) {
+    const destPath = path.join(krackedDir, file);
+    const content = applyTokens(readTemplate(`project/${file}`), tokens);
+    await writeFileWithConflictCheck(destPath, content, ask, report);
+  }
+
+  // sdd/tracker.md + sdd/specs/.gitkeep
+  const trackerDest = path.join(krackedDir, 'sdd', 'tracker.md');
+  const trackerContent = applyTokens(readTemplate('project/sdd/tracker.md'), tokens);
+  await writeFileWithConflictCheck(trackerDest, trackerContent, ask, report);
+
+  const gitkeepDest = path.join(krackedDir, 'sdd', 'specs', '.gitkeep');
+  if (!fs.existsSync(gitkeepDest)) {
+    fs.mkdirSync(path.dirname(gitkeepDest), { recursive: true });
+    fs.writeFileSync(gitkeepDest, '', 'utf8');
+    report({ path: gitkeepDest, action: 'written' });
+  }
+}
+
+/** Write AGENTS.md, CLAUDE.md (shim), and .agents/rules/kracked.md. */
+export async function writeLoaders({ projectDir, tokens, ask, report }) {
+  const agentsContent = applyTokens(readTemplate('loaders/AGENTS.md'), tokens);
+  await writeFileWithConflictCheck(path.join(projectDir, 'AGENTS.md'), agentsContent, ask, report);
+
+  const claudeContent = applyTokens(readTemplate('loaders/CLAUDE.md'), tokens);
+  await writeFileWithConflictCheck(path.join(projectDir, 'CLAUDE.md'), claudeContent, ask, report);
+
+  const krackedRulesContent = applyTokens(readTemplate('loaders/antigravity-rules.md'), tokens);
+  await writeFileWithConflictCheck(
+    path.join(projectDir, '.agents', 'rules', 'kracked.md'),
+    krackedRulesContent,
+    ask,
+    report
+  );
+}
+
+/**
+ * Write the 4 skills to BOTH .claude/skills/<name>/SKILL.md and
+ * .agents/skills/<name>/SKILL.md — but only for the harnesses selected.
+ * `editors` is an array that may contain 'antigravity' and/or 'claude'.
+ */
+export async function writeSkills({ projectDir, tokens, editors, ask, report }) {
+  const targets = [];
+  if (editors.includes('claude')) targets.push('.claude/skills');
+  if (editors.includes('antigravity')) targets.push('.agents/skills');
+
+  for (const skillName of SKILL_NAMES) {
+    const content = applyTokens(readTemplate(`skills/${skillName}/SKILL.md`), tokens);
+    for (const targetBase of targets) {
+      const destPath = path.join(projectDir, targetBase, skillName, 'SKILL.md');
+      await writeFileWithConflictCheck(destPath, content, ask, report);
+    }
+  }
+}