ai-necessities 0.0.0-stage → 1.0.0

package/AGENTS.md-template.md

@@ -0,0 +1,89 @@
+
+# AGENTS.md
+
+## How to plug into a new project
+
+1. Copy this `AI-Necessities/template.agents/` folder into the target project as `.agents/`.
+2. Run `/setup` once. It crawls the project, generates/updates this root `AGENTS.md`, and proposes project-fit skills, commands, and agents.
+3. Approve the proposal before anything is created.
+4. Optional: drop in a stack overlay from `template.agents/overlays/` (react-express, react-next, react-native-expo-supabase) before running `/setup`.
+
+---
+
+## Set up Commands
+
+- `/setup` — one-time project bootstrap: scan, analyze, generate `/pm`, propose project-fit skills/commands/agents, dedupe. Run once per project.
+- `/init` — crawls the project and generates/updates the root `AGENTS.md` with discovered facts only (stack, architecture, conventions, build/test/lint commands). Stack-agnostic; assumes nothing.
+- `/pm <task>` — analyze task against the project profile, plan ordered steps, diagram with Mermaid + ASCII flow, confidence levels per step, then stop for approval before implementing.
+- `/review` — targeted code-review entry point.
+- `/test` — generate/run tests for changed files.
+- `/security-audit` — scan for security issues in changed or new code.
+
+---
+
+## Code Style
+
+- Generate concise, short solutions for new modules or code.
+- Watch for over-engineering and oversized files needing refactor.
+- Watch for weird syntax/style mismatching the rest of the codebase.
+- Watch for obvious bugs and blast radius of errors.
+- No emojis or special characters in comments.
+- Write activity-log.md in /docs to refer back if confused.
+- Markdown files use kebab naming (e.g. `some-description-changes.md`).
+- Comments: one-liner, one sentence.
+
+---
+
+## General Principles
+
+- Right data structures and algorithms for the problem.
+- Don't expose data needlessly (least privilege).
+- No external libraries unless absolutely necessary.
+- Use project dependency file for correct versions.
+- Avoid redundancy unless it improves usability.
+- Run major changes by the user first; do not execute blindly.
+- Review existing files before refactor or change.
+
+---
+
+## Version Control
+
+- Commit after significant changes, clear messages.
+- Keep commits focused and atomic.
+- No auto-push any branch.
+- Don't auto-commit activity logs and docs.
+
+---
+
+## AI Restrictions
+
+- Always check npm/yarn/pub/download safety before installing external libraries.
+- No auto-push any branch.
+- Run major changes by the user first; do not execute blindly.
+- Review existing files before any edit.
+- No em dashes in any writing. Zero tolerance.
+- Keep responses concise and direct unless detail is requested.
+
+---
+
+## Agent Routing (workflow)
+
+When a task arrives:
+
+1. **Analyze** what areas it touches (UI, database, API, security, tests).
+2. **Route** to the respective agent per area:
+   - **designer** — front-end UI/UX, screen redesigns, component layout, styling.
+   - **backend-architect** — database tables, schemas, API structure, server logic.
+   - **reviewer** — code review: style, quality, blast radius, security, conventions.
+   - **tester** — test generation and execution.
+   - **security-auditor** — security scan and audit.
+3. **If multiple areas** (e.g. creating tables AND redesigning the main screen), delegate to each respective agent so they co-work in parallel on their slice.
+4. **Tester follows up** — after all agents finish their slice, the tester generates and runs tests for everything that changed.
+5. **Reviewer checks** — the reviewer reviews the combined output against AGENTS.md.
+6. **Approval gate** — stop before implementing. Present the plan and wait for explicit approval. No auto-execute, no auto-push.
+
+## Agent handoffs
+
+- designer ↔ backend-architect: co-work when a task spans UI + backend/database; hand off to tester after.
+- security-auditor → tester: if audit findings require code changes, tester re-runs tests after fixes.
+- reviewer → approval: reviewer signs off before anything is committed or pushed.

package/README.md

@@ -1,3 +1,64 @@
-# Temporary Holding Version
+# ai-necessities
 
-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.
+> **Work in progress.** This template is continuously getting improved. Expect changes, additions, and refinements as it evolves.
+
+A plug-and-play AI agent template for coding projects. Copy `.agents/` into any project and you get a full agent setup: `/setup`, `/pm`, `/review`, `/test`, and `/security-audit`. Stack-agnostic — works with React, Next.js, Node/Express, Flutter, or anything else.
+
+## What's inside
+
+```
+.ai-necessities/
+├── AGENTS.md-template.md        # Root agent instructions (copy into your project)
+├── template.agents/             # The actual .agents/ folder to drop into projects
+│   ├── commands/                # /setup, /init, /pm, /review, /test, /security-audit
+│   ├── agents/                  # designer, backend-architect, reviewer, tester, security-auditor, researcher
+│   ├── hooks/                   # pre-edit, post-commit safety hooks
+│   ├── skills/                  # skill-discovery (finds and installs relevant skills)
+│   ├── settings/                # agent-config (writing style, safety, model rules)
+│   └── overlays/                # react-express, react-next, react-native-expo-supabase
+├── bin/init.js                  # npm installable: copies .agents/ into your project
+├── package.json
+└── .gitignore
+```
+
+## Quick start
+
+### Option 1: Manual copy (no install)
+
+1. Copy `template.agents/` into your project as `.agents/`.
+2. Run `/setup` once. It scans your project, generates `AGENTS.md`, and proposes project-fit agents/commands/skills.
+3. Approve the proposal before anything is created.
+
+### Option 2: npm install
+
+```bash
+npm install ai-necessities
+npx ai-necessities   # installs .agents/ into your project
+# Then run /setup
+```
+
+## Workflow
+
+When a task arrives:
+
+1. **Analyze** what areas it touches (UI, database, API, security, tests).
+2. **Route** to the right agent — designer, backend-architect, tester, security-auditor, or reviewer.
+3. **If multiple areas** (e.g. creating tables AND redesigning the main screen), agents co-work in parallel on their slice.
+4. **Tester follows up** — generates and runs tests for everything that changed.
+5. **Reviewer checks** — reviews the combined output against AGENTS.md.
+6. **Approval gate** — stop before implementing. Present the plan and wait for explicit approval. No auto-execute, no auto-push.
+
+## Stack overlays
+
+Drop these into `template.agents/overlays/` before running `/setup`:
+- `react-express`
+- `react-next`
+- `react-native-expo-supabase`
+
+## Status
+
+**Work in progress.** Continuously getting improved. Commands, agents, and overlays will be added and refined over time.
+
+## License
+
+MIT

package/bin/init.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const TEMPLATE_DIR = path.join(__dirname, '..', 'template.agents');
+const TARGET_DIR = path.join(process.cwd(), '.agents');
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(dest)) {
+    fs.mkdirSync(dest, { recursive: true });
+  }
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function main() {
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    console.error('Error: template.agents/ not found in package.');
+    process.exit(1);
+  }
+
+  if (fs.existsSync(TARGET_DIR)) {
+    console.log('.agents/ already exists in this project. Skipping copy.');
+    console.log('Run /setup to initialize agents, or delete .agents/ and re-run to overwrite.');
+    process.exit(0);
+  }
+
+  copyDir(TEMPLATE_DIR, TARGET_DIR);
+  console.log('.agents/ installed into this project.');
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review the files under .agents/');
+  console.log('  2. Run /setup to initialize agents for this project.');
+}
+
+main();

package/package.json

@@ -1,6 +1,19 @@
 {
   "name": "ai-necessities",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Plug-and-play AI agent template for coding projects. Copies .agents/ into your project so you can run /setup, /pm, /review, /test, and /security-audit.",
+  "main": "bin/init.js",
+  "bin": {
+    "ai-necessities": "bin/init.js"
+  },
+  "files": [
+    "template.agents/",
+    "AGENTS.md-template.md",
+    "bin/"
+  ],
+  "scripts": {
+    "init": "node bin/init.js"
+  },
+  "keywords": ["ai", "agents", "template", "coding", "automation"],
+  "license": "MIT"
+}

package/template.agents/agents/backend-architect.md

@@ -0,0 +1,14 @@
+# Agent: backend-architect
+
+## Scope
+- Database tables and schemas
+- API structure and endpoints
+- Server logic and backend modules
+- Data layer and service logic
+
+## Rules
+- Follow AGENTS.md — Code Style, General Principles, Version Control, and AI Restrictions apply in full.
+- Run major backend changes by the user first; do not execute blindly.
+
+## Handoff
+- When a task touches both backend and UI, co-work with designer, then hand off to tester for follow-up.

package/template.agents/agents/designer.md

@@ -0,0 +1,15 @@
+# Agent: designer (front-end)
+
+## Scope
+- Front-end UI/UX
+- Screen redesigns
+- Component layout and styling
+- User-facing interactions
+
+## Rules
+- Follow AGENTS.md — Code Style, General Principles, Version Control, and AI Restrictions apply in full.
+- Match existing component patterns; do not introduce new design systems unless approved.
+- Run major UI changes by the user first; do not execute blindly.
+
+## Handoff
+- When a task touches both UI and backend/database, co-work with backend-architect, then hand off to tester for follow-up.

package/template.agents/agents/researcher.md

@@ -0,0 +1,10 @@
+# Agent: researcher (placeholder)
+
+## Purpose
+Handles code-review purpose lookups and best-practice research on demand.
+
+## Status
+Deferred. The user wants to discuss code-review purpose and setup later. When summoned, this subagent will:
+1. Research what code review is for in this project's context.
+2. Return a short, concise, direct summary: purpose, right setup, best practices.
+3. Not write code or change files until approved.

package/template.agents/agents/reviewer.md

@@ -0,0 +1,8 @@
+# Agent: reviewer
+
+## Scope
+- Code review: style, quality, blast radius, security, conventions
+- Review existing files before refactor or change
+
+## Handoff
+- Reviews are triggered by /review or as a follow-up step after designer/backend-architect/tester complete work.

package/template.agents/agents/security-auditor.md

@@ -0,0 +1,15 @@
+# Agent: security-auditor
+
+## Scope
+- Security scan and audit of new or changed code
+- Dependency safety check (npm/yarn/pub/download)
+- Auth, input validation, and data exposure review
+
+## Rules
+- Follow AGENTS.md — Code Style, General Principles, Version Control, and AI Restrictions apply in full.
+- Check for injection points, unsafe defaults, and hardcoded secrets.
+- Report findings; do not auto-push or auto-fix without user approval.
+
+## Handoff
+- Triggered by /security-audit or as a follow-up step after designer/backend-architect complete work.
+- Hand off to tester if code changes are needed based on findings.

package/template.agents/agents/tester.md

@@ -0,0 +1,13 @@
+# Agent: tester
+
+## Scope
+- Test generation for new or changed code
+- Test execution and reporting
+
+## Rules
+- Follow AGENTS.md — Code Style, General Principles, Version Control, and AI Restrictions apply in full.
+- Use project test runner and dependency file for correct versions.
+
+## Handoff
+- Receives hand-off from designer, backend-architect, or security-auditor after their work is done.
+- Runs test suite for affected files and reports results.

package/template.agents/commands/init.md

@@ -0,0 +1,18 @@
+# /init
+
+Run this once per project. It crawls the project and generates or updates the root `AGENTS.md` — the only source of discovery for stack, architecture, conventions, and commands.
+
+This command is stack-agnostic. It assumes nothing about language, framework, or architecture. All stack-specific detail comes from what it observes in the codebase.
+
+## Steps
+
+1. **Crawl the project** — list top-level folders, config files, dependency files, scripts, and entry points.
+2. **Detect the stack** — from dependency files and imports (e.g. package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml).
+3. **Detect the architecture/layer pattern** — from folder layout (e.g. client/server split, feature modules, src/pages + src/components, app/api).
+4. **Extract conventions** — naming style, comment style, test file placement, lint/format config.
+5. **Extract build/test/lint commands** — from package.json scripts, Makefile, or similar.
+6. **Write or update root `AGENTS.md`** — populate only the observed facts. Do not hand-write architecture facts before this runs.
+
+## Output
+
+The resulting `AGENTS.md` becomes the project profile that `/setup` Phase 1 reads from. Every later phase reasons from this profile, never re-derives it from scratch.

package/template.agents/commands/pm.md

@@ -0,0 +1,33 @@
+# /pm <task>
+
+Plan, diagram, and get approval before implementing any task.
+
+## Contract
+
+On every `/pm <task>` invocation:
+
+1. **Analyze** the task against the Phase 1 project profile from root `AGENTS.md` (stack, architecture, conventions, build/test/lint commands).
+2. **Plan** — ordered implementation steps.
+3. **Diagram** — a Mermaid diagram scoped to what this task touches, plus the same flow re-rendered as plain-text ASCII box/arrow diagram directly in the response.
+4. **Flow diagram** — adapt node content to the layer the task touches (UI taps/screens for client code, requests/handlers/DB calls for backend code, or both if it spans the boundary).
+   - Use `╔══╗` / `╚══╝` double-border boxes for user-initiated or external-caller-initiated actions (entry/exit points).
+   - Use `┌──┐` / `└──┘` single-border boxes for system steps (UI state changes, middleware, handlers, DB calls, service logic).
+   - Use `┌───┐` / `└───┘` with a question inside for decision nodes (e.g. `Auth valid?`, `Cache hit?`, `Form valid?`).
+   - Branch with `Yes` / `No` labels on fork lines.
+   - Cover the happy path plus key edge branches visible to the caller (error states, validation failures, empty states).
+   - Keep it concise: 4–12 nodes maximum.
+5. **Confidence level** — a percentage (0-100%) per plan step, with a one-line reason. Any step below 90% must come with the specific clarifying question that resolves the unclear area.
+6. **Approval gate** — stop here. Do not implement, edit files, or delegate to any other command until the person explicitly approves the plan.
+
+## Agent routing
+
+When a task spans multiple areas, delegate to each respective agent so they co-work, then hand off to tester for follow-up:
+- **designer** — front-end UI/UX, screen redesigns, component layout, styling.
+- **backend-architect** — database tables, schemas, API structure, server logic.
+- **reviewer** — code review: style, quality, blast radius, security, conventions.
+- **tester** — test generation and execution.
+- **security-auditor** — security scan and audit.
+
+## Output
+
+Present the plan, diagrams, and confidence levels. End with: "Approve this plan before I implement anything."

package/template.agents/commands/review.md

@@ -0,0 +1,24 @@
+# /review
+
+Targeted code-review entry point. Reviews existing files before refactor or change, and checks agent-generated code like a junior's PR.
+
+## Contract
+
+On every `/review` invocation:
+
+1. **Identify** the files under review (changed, new, or agent-generated files).
+2. **Read** each file in full — never review blindly.
+3. **Check against AGENTS.md** — Code Style, General Principles, Version Control, AI Restrictions.
+   - Concise, short solutions; no over-engineering or oversized files needing refactor.
+   - No syntax/style mismatching the rest of the codebase.
+   - No obvious bugs; check blast radius of errors.
+   - No emojis or special characters in comments; comments are one-liner, one sentence.
+   - Markdown files use kebab naming.
+4. **Check security** — no hardcoded secrets, no unsanitized input, no missing auth on routes, least-privilege data exposure.
+5. **Run automated checks** — ESLint, TypeScript type check, tests — so the review focuses on logic, not style.
+6. **Report findings** — file, line, issue, severity, recommended fix. Approve when good; request changes when not.
+7. **No auto-push any branch.**
+
+## Output
+
+A short list of review findings, or "Approved" with no comments if everything passes.

package/template.agents/commands/security-audit.md

@@ -0,0 +1,17 @@
+# /security-audit
+
+Scan new or changed code for security issues.
+
+## Steps
+
+1. Identify changed or new files from the task scope.
+2. Check for hardcoded secrets, credentials, or API keys.
+3. Check for injection points (SQL, command, script) in user-facing input.
+4. Check data exposure — least privilege: is more data returned than needed?
+5. Check dependency safety — run the download safety check from AGENTS.md AI Restrictions.
+6. Report findings with severity and recommended fix.
+7. Do not auto-fix or auto-push; stop for user approval before any changes.
+
+## Output
+
+A short list of findings: file, line, issue, severity, fix. If none, report "No security issues found."

package/template.agents/commands/test.md

@@ -0,0 +1,24 @@
+# /test
+
+Generate and run tests for new or changed code.
+
+## Contract
+
+On every `/test` invocation:
+
+1. **Identify** changed or new files from the task scope.
+2. **Generate** tests for those files if they don't exist, matching the project's test framework and patterns.
+3. **Run** the project's test suite for affected files using the commands from root `AGENTS.md` (e.g. `npm test`, per-folder test scripts).
+4. **Report** results — pass/fail per test file, failures with details.
+5. **No auto-commit activity logs and docs.** Do not auto-push any branch.
+6. **Hand off back to reviewer or the originating agent** if failures need fixing.
+
+## Rules
+
+- Follow AGENTS.md Code Style and General Principles.
+- Use the project's test runner and dependency file for correct versions.
+- Report failures; do not auto-push.
+
+## Output
+
+Test results: which files passed, which failed, and failure details. If no tests exist yet, report "No tests found for <files>."

package/template.agents/hooks/post-commit.md

@@ -0,0 +1,7 @@
+# Hook: post-commit
+
+Runs after a commit.
+
+1. Run lint and test commands from AGENTS.md.
+2. Skip activity logs and docs (per AGENTS.md Version Control section).
+3. Report failures; do not auto-push any branch.

package/template.agents/hooks/pre-edit.md

@@ -0,0 +1,8 @@
+# Hook: pre-edit
+
+Runs before any file edit.
+
+1. Read the existing file(s) first — never edit blindly.
+2. Confirm with the user if the change is major (new module, API surface change, database change, or >50 lines).
+3. Check AGENTS.md for code style and conventions before writing.
+4. No auto-commit activity logs and docs.

package/template.agents/overlays/react-express/README.md

@@ -0,0 +1,18 @@
+# Stack overlay: react-express
+
+## Detected stack
+React front-end + Express back-end (split or monorepo).
+
+## Conventions
+- Client: `client/` or `frontend/` folder; React components in kebab-case files.
+- Server: `server/` or `backend/` folder; Express routes and controllers.
+- Shared types: `shared/` or `types/` folder if present.
+- Build: `npm run build` (client), `npm start` or `node server/index.js` (server).
+- Test: `npm test` per folder; Jest or Vitest.
+- Lint: `npm run lint`; ESLint config at root or per folder.
+
+## Overlay rules
+- No external libraries unless absolutely necessary.
+- Check download safety before installing.
+- Run major changes by the user first.
+- No auto-push any branch.

package/template.agents/overlays/react-native-expo-supabase/README.md

@@ -0,0 +1,19 @@
+# Stack overlay: react-native-expo-supabase
+
+## Detected stack
+React Native (Expo) + Supabase backend.
+
+## Conventions
+- App: Expo router or navigation folder; components in kebab-case.
+- Supabase: `supabase/` folder with migrations and client config.
+- State: check for existing state management (Zustand, Context, etc.).
+- Build: `npx expo build` or `npx expo prebuild`.
+- Test: `npm test`; Jest with Expo preset.
+- Lint: `npm run lint`; ESLint config at root.
+
+## Overlay rules
+- No external libraries unless absolutely necessary.
+- Check download safety before installing (Expo SDK + Supabase packages).
+- Run major changes by the user first.
+- No auto-push any branch.
+- Supabase migrations: review before applying; no auto-migrate.

package/template.agents/overlays/react-next/README.md

@@ -0,0 +1,18 @@
+# Stack overlay: react-next
+
+## Detected stack
+Next.js (React) full-stack or front-end only.
+
+## Conventions
+- App router: `app/` folder with route handlers and page components.
+- Components: `components/` folder; kebab-case file names.
+- Styling: Tailwind CSS; check `tailwind.config.ts` for existing conventions.
+- Build: `npm run build`; dev: `npm run dev`.
+- Test: `npm test`; Jest or Vitest.
+- Lint: `npm run lint`; ESLint config at root.
+
+## Overlay rules
+- No external libraries unless absolutely necessary.
+- Check download safety before installing.
+- Run major changes by the user first.
+- No auto-push any branch.

package/template.agents/settings/agent-config.md

@@ -0,0 +1,18 @@
+# Agent Settings
+
+## Writing style
+- No em dashes in any writing. Zero tolerance.
+- Concise, short, direct answers unless detail is requested.
+- Plain language by default; avoid jargon unless asked for technical depth.
+
+## Markdown
+- Kebab-case naming for markdown files (e.g. `some-description-changes.md`).
+- Comments: one-liner, one sentence.
+- No emojis or special characters in comments.
+
+## Model & context
+- Default model: match project complexity; prefer faster/cheaper models for routine edits, larger models for architecture and review.
+- Context limit: summarize before approaching limits; keep conversation focused on the current task.
+
+## Safety
+- Follow AGENTS.md Version Control and AI Restrictions (no auto-push, run major changes by user first, check download safety, no external libraries unless necessary).

package/template.agents/skills/skill-discovery/SKILL.md

@@ -0,0 +1,22 @@
+# Skill: skill-discovery
+
+## Purpose
+
+Find skills relevant to the current project and propose them for user confirmation before installing. Never installs speculative infrastructure the user hasn't confirmed.
+
+## Flow
+
+1. Read the project profile from root `AGENTS.md` (stack, architecture, conventions).
+2. Scan `.agents/skills/` for existing skills.
+3. Compare project needs against available skill templates:
+   - UI-fidelity checklist → for client apps with UI work
+   - API-contract checklist → for backend services with API changes
+   - Release checklist → for projects with deploy/release steps
+   - Any other skill matching the detected stack or workflow
+4. Propose the list with a one-line rationale per item.
+5. Stop for user confirmation before installing any skill.
+6. Install only confirmed skills into `.agents/skills/`.
+
+## Rule
+
+Do not default to any skill set. The project profile determines what's proposed. A project with no clear layer split shouldn't get skills just because that pattern exists elsewhere.