spacekid 0.0.0-stage → 0.1.0

package/bin/spacekid.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+'use strict';
+
+const { main } = require('../src/cli');
+
+process.exitCode = main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,29 @@
 {
   "name": "spacekid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A minimalist spec kit for agentic development.",
+  "license": "MIT",
+  "bin": {
+    "spacekid": "bin/spacekid.js"
+  },
+  "main": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/src/cli.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('node:path');
+const { parseArgs } = require('node:util');
+
+const { scaffold } = require('./scaffold');
+
+const STATUS_LABEL = {
+  created: 'created',
+  appended: 'appended to',
+  skipped: 'skipped (already exists)',
+};
+
+const USAGE = `usage: spacekid init [--path <dir>] [--name <name>]
+
+  init    scaffold the SpaceKid AGENTS.md cycle in a project
+`;
+
+function init(args) {
+  const { values } = parseArgs({
+    args,
+    options: {
+      path: { type: 'string', default: '.' },
+      name: { type: 'string' },
+    },
+    allowPositionals: false,
+  });
+
+  const projectRoot = path.resolve(values.path);
+  for (const result of scaffold(projectRoot, values.name)) {
+    console.log(`${STATUS_LABEL[result.status]}: ${path.relative(projectRoot, result.path)}`);
+  }
+  return 0;
+}
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (command !== 'init') {
+    process.stderr.write(USAGE);
+    return 1;
+  }
+  try {
+    return init(rest);
+  } catch (err) {
+    process.stderr.write(`spacekid: ${err.message}\n${USAGE}`);
+    return 1;
+  }
+}
+
+module.exports = { main };

package/src/index.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./scaffold');

package/src/scaffold.js

@@ -0,0 +1,68 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const APP_NAME_PLACEHOLDER = '{{APP_NAME}}';
+const TEMPLATES_DIR = path.join(__dirname, 'templates');
+
+function loadTemplate(filename) {
+  return fs.readFileSync(path.join(TEMPLATES_DIR, filename), 'utf8');
+}
+
+function detectAppName(projectRoot) {
+  const manifest = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(manifest)) {
+    try {
+      const { name } = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      if (typeof name === 'string' && name.length > 0) {
+        return name;
+      }
+    } catch {
+      // Unreadable or malformed package.json: fall back to the directory name.
+    }
+  }
+  return path.basename(path.resolve(projectRoot));
+}
+
+function renderRootAgents(appName) {
+  return loadTemplate('root-agents.md').split(APP_NAME_PLACEHOLDER).join(appName);
+}
+
+function writeOrSkip(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    return { path: filePath, status: 'skipped' };
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  return { path: filePath, status: 'created' };
+}
+
+function writeOrAppend(filePath, content) {
+  if (fs.existsSync(filePath)) {
+    fs.appendFileSync(filePath, '\n' + content, 'utf8');
+    return { path: filePath, status: 'appended' };
+  }
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+  return { path: filePath, status: 'created' };
+}
+
+function scaffold(projectRoot, appName) {
+  const root = path.resolve(projectRoot);
+  const resolvedName = appName || detectAppName(root);
+
+  return [
+    writeOrSkip(path.join(root, 'AGENTS.md'), renderRootAgents(resolvedName)),
+    writeOrAppend(path.join(root, 'specs', 'AGENTS.md'), loadTemplate('specs-agents.md')),
+    writeOrAppend(path.join(root, 'plans', 'AGENTS.md'), loadTemplate('plans-agents.md')),
+  ];
+}
+
+module.exports = {
+  detectAppName,
+  renderRootAgents,
+  writeOrSkip,
+  writeOrAppend,
+  scaffold,
+};

package/src/templates/plans-agents.md

@@ -0,0 +1,62 @@
+# AGENTS.md — Writing Implementation Plans
+
+A plan translates a spec into a **technical design**: how it will be built,
+with the highest quality and best software engineering practices.
+
+Follow the same writing discipline as `specs/AGENTS.md` — concise, clear,
+no fluff — applied here to engineering rather than business content.
+
+## Guiding principles
+
+- **KISS.** The simplest design that correctly satisfies the spec wins.
+  Well-executed simplicity beats clever complexity every time.
+- **SOLID.** Apply these principles where they add real value — not as
+  ceremony.
+- **Scalability & maintainability.** Design for the load and change patterns
+  the spec actually implies, not speculative future needs. Don't build for
+  hypothetical requirements.
+
+## Rules
+
+- **One plan per spec**, named identically: `plans/<name>.md` implements
+  `specs/<name>.md`.
+- **This file may reference its spec** — it should open by linking to
+  `specs/<name>.md`. This is the only direction references flow: specs never
+  reference plans.
+- **English only.**
+
+## Structure
+
+```markdown
+# <Feature Name> — Implementation Plan
+
+Implements: `specs/<name>.md`
+Status: Draft | Approved | In Progress | Done
+
+## Approach
+The chosen technical approach and why it's the simplest one that satisfies
+the spec.
+
+## Steps
+Ordered, concrete implementation steps.
+
+## Key Decisions
+Notable design/architecture choices and their trade-offs (only if non-obvious).
+
+## Implementation Notes
+Filled in after the work is done: what changed vs. the original plan, and
+why (edge cases found, constraints discovered, simplifications made).
+```
+
+## After implementation — mandatory
+
+As soon as the implementation is finished:
+
+1. Set `Status: Done`.
+2. Fill in **Implementation Notes** with any deviation from the original plan
+   and the reason for it.
+3. Go back to `specs/<name>.md` and update its status per `specs/AGENTS.md`.
+4. If this work affected the behavior of any other already-implemented
+   spec/plan pair, update those too.
+
+Never consider a task finished while this update step is pending.

package/src/templates/root-agents.md

@@ -0,0 +1,49 @@
+# Agent Guide — {{APP_NAME}}
+
+## Project Overview
+
+<!--
+AGENT TODO: This section is a placeholder. Replace it as soon as you have
+enough context about this specific project — its purpose, its intended
+users, and any key constraints or decisions that shape it. Do this the
+first time you work on a real feature here, not before you actually know
+the answers. Once this section reflects the real project, delete this
+comment block; a placeholder left in place after that point is a bug in
+this file, not a feature.
+-->
+
+_Not yet described. Fill in what this project does, who it's for, and any
+constraints that matter before writing the first spec._
+
+## Purpose
+
+This file orients any agent working in this repository. It maps where the rules live and defines the mandatory cycle that connects business intent, engineering planning, and implementation.
+
+## Project Map
+
+- `AGENTS.md` (this file) — the map, the cycle, and this project's overview.
+- `specs/AGENTS.md` — how to write a spec. Read this before writing or editing anything in `specs/`.
+- `specs/*.md` — one spec per feature. Business-only, self-contained.
+- `plans/AGENTS.md` — how to write an implementation plan. Read this before writing or editing anything in `plans/`.
+- `plans/*.md` — one implementation plan per feature, paired with its spec by matching slug (e.g. `specs/foo-spec.md` ↔ `plans/foo-plan.md`).
+- This project's own architecture or coding-convention guide, if one has been added — read it before writing or editing implementation code.
+
+## The Cycle
+
+Every non-trivial feature must flow through these steps, in order:
+
+1. **Spec.** Write or update a spec in `specs/`, following `specs/AGENTS.md`. It captures the business problem, what must be delivered, and acceptance criteria — nothing about how.
+2. **Plan.** Write or update an implementation plan in `plans/`, following `plans/AGENTS.md`. It references the spec and lays out the engineering approach.
+3. **Implementation.** Build the feature following the plan and this project's own conventions.
+4. **Close the loop.** As soon as implementation finishes:
+   - Update the plan's Status and its Adaptations Log with anything that changed from the original plan during the build.
+   - Update the spec's Status to reflect that it is now implemented.
+5. **Stay current.** If later work touches an area already covered by an existing spec or plan — even when that wasn't the original goal of the task — revisit and update those files too, so they never go stale.
+
+## Rules Agents Must Never Break
+
+- Never implement a non-trivial feature without a spec in `specs/` and a plan in `plans/` already in place.
+- Never finish an implementation task without updating the Status of both the plan and its spec.
+- Never let a spec or plan go stale after a related change lands elsewhere in the codebase — step 5 is not optional.
+- Never write a spec that contains implementation details, or a plan that skips referencing its spec.
+- Never leave the Project Overview placeholder above unfilled once the project's purpose is actually known.

package/src/templates/specs-agents.md

@@ -0,0 +1,55 @@
+# AGENTS.md — Writing Specs
+
+A spec captures the **business intent** of a feature: why it exists, what it
+must do, and how we know it's done. Nothing more.
+
+## Rules
+
+- **Self-contained.** A reader must understand the full spec without opening
+  any other file. Do not reference other specs, plans, code files, or paths.
+- **No implementation detail.** No code, no technology choices, no
+  architecture, no data models. That belongs exclusively in the matching
+  `plans/<name>.md`.
+- **Concise and clear.** Say only what's needed to preserve the core idea.
+  Prefer short sentences and bullet lists over long prose. Cut anything that
+  doesn't change what gets built or how it's accepted.
+- **Business-only scope.** A spec centralizes business points: context,
+  problem, what must be delivered, and acceptance criteria. It does not
+  belong to engineering.
+- **English only.**
+
+## Structure
+
+```markdown
+# <Feature Name>
+
+Status: Draft | Approved | Implemented
+
+## Context
+Why this is needed. The problem or opportunity, in business terms.
+
+## Requirements
+What must exist or happen once this is delivered. Plain, unambiguous
+statements — no solution design.
+
+## Acceptance Criteria
+A checklist of verifiable conditions that define "done".
+
+## Out of Scope
+What this spec explicitly does not cover (optional, only if it prevents
+ambiguity).
+```
+
+## What happens next
+
+The implementation plan for this spec is written in `plans/<name>.md`
+(same `<name>`), following `plans/AGENTS.md`. The plan file is the only place
+allowed to reference this spec — this spec must never reference the plan or
+any code.
+
+## Status updates
+
+Once the feature is implemented, the `Status` field here must be updated to
+`Implemented`. If real-world constraints forced any acceptance criteria to
+change during implementation, update this file to reflect what was actually
+delivered.

package/types/index.d.ts

@@ -0,0 +1,10 @@
+export interface FileResult {
+  path: string;
+  status: 'created' | 'appended' | 'skipped';
+}
+
+export function detectAppName(projectRoot: string): string;
+export function renderRootAgents(appName: string): string;
+export function writeOrSkip(filePath: string, content: string): FileResult;
+export function writeOrAppend(filePath: string, content: string): FileResult;
+export function scaffold(projectRoot: string, appName?: string): FileResult[];

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.