@p_tipso/agentive 1.0.0 → 1.0.1

package/README.md

@@ -1,4 +1,4 @@
-<![CDATA[<div align="center">
+<div align="center">
 
 # 🤖 agentive
 
@@ -12,77 +12,123 @@
 
 ---
 
-Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a single `.agent/` directory in your project — your source of truth for agent rules and skills — and compiles it into the specific formats each AI tool understands.
+Stop maintaining separate rule files for every AI tool. **agentive** scaffolds a universal `.agents/` directory and an `AGENTS.md` file in your project — your single source of truth for agent commands, skills, and rules.
 
 ## ✨ What it does
 
-1. **Scaffolds** a universal `.agent/` workspace in your project
-2. **Syncs** your `.agent/` files into the native formats of your chosen AI tools:
-   - 🖱 **Cursor** → `.cursor/rules/`
-   - 🤖 **Claude** → `CLAUDE.md`
-   - 🌊 **Windsurf** → `.windsurfrules`
-
----
-
-## 🚀 Quick Start
+Run one command, get a fully structured AI agent workspace:
 
 ```bash
 npx @p_tipso/agentive
 ```
 
-The interactive wizard will ask you:
-1. **Project name** (pre-filled from your directory name)
-2. **Your primary tech stack** (e.g. "Next.js, TypeScript, Postgres")
-3. **Which AI tools** you use (multi-select: Cursor, Claude, Windsurf)
+No prompts. No config. Just run it and it scaffolds everything instantly into the folder your terminal is currently in.
+
+### What happens when you run it
 
-Then it scaffolds everything automatically.
+1. Detects your current directory and project name
+2. Creates an `AGENTS.md` file at your project root (top-level agent instructions)
+3. Creates a `.agents/` folder with the full workspace structure:
+   - `settings.json` — project config (committed to git)
+   - `settings.local.json` — local machine overrides (auto-gitignored)
+   - `commands/` — reusable prompt commands (e.g. code review, fix errors)
+   - `skills/` — skill definitions for agent roles
+   - `rules/` — project-wide rules all agents must follow
+4. If `.agents/` already exists, it skips to avoid overwriting your customisations
 
 ---
 
 ## 📁 Output Structure
 
-After running `npx @p_tipso/agentive`, your project will have:
-
 ```
 your-project/
-├── .agent/
-│   ├── settings.json          ← project config (commit this)
-│   ├── settings.local.json    ← local overrides (gitignored automatically)
-│   ├── rules/
-│   │   └── architecture.md    ← project-wide rules for all agents
-│   └── skills/
-│       ├── web-browser.md         ← how agents should browse the web
-│       ├── data-extractor.md      ← how agents should extract data
-│       ├── data-transformer.md    ← how agents should transform data
-│       └── output-dispatcher.md   ← how agents should deliver output
-│
-│   ── (auto-synced based on your selection) ──
-│
-├── .cursor/rules/             ← if you selected Cursor
-├── CLAUDE.md                  ← if you selected Claude
-└── .windsurfrules             ← if you selected Windsurf
+├── AGENTS.md                      ← root agent instructions
+├── .agents/
+│   ├── settings.json              ← project config
+│   ├── settings.local.json        ← local overrides (auto-gitignored)
+│   ├── commands/
+│   │   ├── README.md              ← guide: how to add commands
+│   │   ├── review.md              ← code review command
+│   │   └── fix-issue.md           ← zero-error fix command
+│   ├── skills/
+│   │   └── README.md              ← guide: how to add skills
+│   └── rules/
+│       └── README.md              ← guide: how to add rules
 ```
 
-### `settings.json` example
+### `settings.json`
 
 ```json
 {
   "projectName": "my-app",
-  "techStack": "Next.js, TypeScript, PostgreSQL",
-  "tools": ["cursor", "claude"],
-  "agentiveVersion": "1.0.0",
+  "agentiveVersion": "1.1.0",
   "createdAt": "2026-07-05T12:00:00.000Z"
 }
 ```
 
 ---
 
+## 🏗 Package Architecture
+
+This is the source code structure of the `agentive` npm package itself:
+
+```
+agentive/
+├── bin/
+│   └── index.js                   ← CLI entry point (shebang + commander)
+├── src/
+│   ├── commands/
+│   │   └── init.js                ← scaffolding logic (no prompts, auto-install)
+│   ├── templates/                 ← files copied into the user's project
+│   │   ├── AGENTS.md              ← → copied to project root
+│   │   ├── commands/
+│   │   │   ├── README.md
+│   │   │   ├── review.md
+│   │   │   └── fix-issue.md
+│   │   ├── skills/
+│   │   │   └── README.md
+│   │   └── rules/
+│   │       └── README.md
+│   └── utils/
+│       ├── fileSystem.js          ← async fs helpers, directory creation, settings
+│       └── compilers.js           ← sync to Cursor / Claude / Windsurf formats
+├── .github/
+│   └── workflows/
+│       └── publish.yml            ← auto-publish to npm on git tag push
+├── .gitignore
+├── LICENSE
+├── README.md
+└── package.json
+```
+
+---
+
+## 📂 Folder Guide
+
+### Commands (`commands/`)
+
+Reusable prompt instructions that agents can execute on demand.
+
+| File | Purpose |
+|------|---------|
+| `review.md` | Structured code review for bugs, performance, and security |
+| `fix-issue.md` | Diagnose and fix errors with zero tolerance |
+
+### Skills (`skills/`)
+
+Skill definitions that teach agents how to behave in specific roles. Add `.md` files to define new capabilities.
+
+### Rules (`rules/`)
+
+Project-wide rules that all agents must follow. Add `.md` files for coding standards, architecture rules, etc.
+
+---
+
 ## 📦 Commands
 
 | Command | Description |
 |---|---|
-| `npx @p_tipso/agentive` | Run the setup wizard and scaffold your `.agent/` workspace |
-| `npx @p_tipso/agentive init` | Same as above (explicit subcommand) |
+| `npx @p_tipso/agentive` | Scaffold `.agents/` workspace instantly |
 | `npx @p_tipso/agentive --version` | Print the current version |
 | `npx @p_tipso/agentive --help` | Show available commands |
 
@@ -90,8 +136,6 @@ your-project/
 
 ## 🛠 Install Globally (optional)
 
-If you use this frequently, install it globally:
-
 ```bash
 npm install -g @p_tipso/agentive
 agentive
@@ -99,18 +143,6 @@ agentive
 
 ---
 
-## 🔄 Re-syncing
-
-Edited your `.agent/` files and want to push changes to Cursor, Claude, etc.? Just re-run:
-
-```bash
-npx @p_tipso/agentive
-```
-
-It will detect the existing `.agent/` directory and ask before overwriting.
-
----
-
 ## 🤝 Contributing
 
 1. Fork the repo: [github.com/TiPS0/agentive](https://github.com/TiPS0/agentive)
@@ -124,4 +156,3 @@ It will detect the existing `.agent/` directory and ask before overwriting.
 ## 📄 License
 
 MIT © [Pakawat Tipso](https://github.com/TiPS0)
-]]>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@p_tipso/agentive",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "A universal, framework-agnostic AI agent repository setup CLI. Scaffold a .agent/ workspace and sync to Cursor, Claude, and Windsurf.",
   "license": "MIT",
   "author": "Pakawat Tipso",
@@ -33,7 +33,7 @@
     "type": "git",
     "url": "git+https://github.com/TiPS0/agentive.git"
   },
-  "homepage": "https://github.com/TiPS0/agentive#readme",
+  "homepage": "https://github.com/TiPS0/agentive",
   "bugs": {
     "url": "https://github.com/TiPS0/agentive/issues"
   },

package/src/commands/init.js

@@ -1,7 +1,6 @@
 'use strict';
 
 const path = require('path');
-const prompts = require('prompts');
 const chalk = require('chalk');
 const { version } = require('../../package.json');
 const {
@@ -10,138 +9,60 @@ const {
   agentDirectoryExists,
   writeSettings,
 } = require('../utils/fileSystem');
-const { syncToCursor, syncToClaude, syncToWindsurf } = require('../utils/compilers');
-
-const AI_TOOLS = [
-  { title: '🖱  Cursor',   value: 'cursor',   description: 'Generates .cursor/rules/' },
-  { title: '🤖  Claude',   value: 'claude',   description: 'Generates CLAUDE.md' },
-  { title: '🌊  Windsurf', value: 'windsurf', description: 'Generates .windsurfrules' },
-];
 
 async function runInit() {
   const cwd = process.cwd();
+  const projectName = path.basename(cwd);
 
   console.log('');
   console.log(chalk.bold.cyan('  🤖 agentive') + chalk.gray(' — Universal AI Agent Workspace Setup'));
   console.log(chalk.gray('  ─────────────────────────────────────────────'));
   console.log('');
 
-  // --- Guard: check if .agent/ already exists ---
+  // --- Guard: check if .agents/ already exists ---
   const alreadyExists = await agentDirectoryExists(cwd);
   if (alreadyExists) {
-    const { overwrite } = await prompts({
-      type: 'confirm',
-      name: 'overwrite',
-      message: chalk.yellow('A .agent/ directory already exists. Overwrite it?'),
-      initial: false,
-    });
-
-    if (!overwrite) {
-      console.log('');
-      console.log(chalk.gray('  Aborted. Your existing .agent/ directory was not modified.'));
-      console.log('');
-      process.exit(0);
-    }
+    console.log(chalk.yellow('  ⚠ ') + chalk.white('.agents/ already exists — skipping (no files were modified).'));
+    console.log(chalk.gray('  Delete .agents/ first if you want to re-scaffold.'));
+    console.log('');
+    process.exit(0);
   }
 
-  // --- Wizard ---
-  const projectName = path.basename(cwd);
-
-  const answers = await prompts(
-    [
-      {
-        type: 'text',
-        name: 'projectName',
-        message: 'Project name?',
-        initial: projectName,
-        validate: (v) => v.trim().length > 0 || 'Required.',
-      },
-      {
-        type: 'text',
-        name: 'techStack',
-        message: 'Primary tech stack?',
-        placeholder: 'e.g. Next.js, TypeScript, PostgreSQL',
-        validate: (v) => v.trim().length > 0 || 'Required.',
-      },
-      {
-        type: 'multiselect',
-        name: 'tools',
-        message: 'Which AI tools do you want to target?',
-        choices: AI_TOOLS,
-        min: 1,
-        hint: '- Space to select. Return to submit',
-        instructions: false,
-      },
-    ],
-    {
-      onCancel: () => {
-        console.log('');
-        console.log(chalk.gray('  Setup cancelled.'));
-        process.exit(0);
-      },
-    }
-  );
-
-  const { tools, techStack } = answers;
-  const finalProjectName = answers.projectName;
-
-  console.log('');
-  console.log(chalk.gray('  Setting up your workspace...'));
+  console.log(chalk.gray('  Installing to: ') + chalk.white(cwd));
   console.log('');
 
-  // --- Scaffold .agent/ directory ---
+  // --- Scaffold .agents/ directory ---
   const templatesDir = path.join(__dirname, '..', 'templates');
-  const agentDir = await createAgentDirectory(cwd, alreadyExists);
-  await copyTemplates(templatesDir, agentDir, techStack);
+  const agentsDir = await createAgentDirectory(cwd, false);
+  await copyTemplates(templatesDir, agentsDir, projectName);
 
   // --- Write settings.json and settings.local.json ---
-  await writeSettings(agentDir, {
-    projectName: finalProjectName,
-    techStack,
-    tools,
+  await writeSettings(agentsDir, {
+    projectName,
     agentiveVersion: version,
     createdAt: new Date().toISOString(),
   });
 
-  console.log(chalk.green('  ✔ ') + chalk.white('Scaffolded ') + chalk.cyan('.agent/') + chalk.white(' workspace'));
-
-  // --- Sync to selected tools ---
-  const compilers = {
-    cursor: syncToCursor,
-    claude: syncToClaude,
-    windsurf: syncToWindsurf,
-  };
-
-  const toolLabels = {
-    cursor:   '.cursor/rules/',
-    claude:   'CLAUDE.md',
-    windsurf: '.windsurfrules',
-  };
-
-  for (const tool of tools) {
-    try {
-      await compilers[tool](agentDir, cwd, techStack);
-      console.log(chalk.green('  ✔ ') + chalk.white('Synced → ') + chalk.cyan(toolLabels[tool]));
-    } catch (err) {
-      console.log(chalk.red('  ✘ ') + chalk.white(`Failed to sync ${tool}: `) + chalk.gray(err.message));
-    }
-  }
+  console.log(chalk.green('  ✔ ') + chalk.white('Created ') + chalk.cyan('AGENTS.md'));
+  console.log(chalk.green('  ✔ ') + chalk.white('Scaffolded ') + chalk.cyan('.agents/') + chalk.white(' workspace'));
 
   // --- Done ---
   console.log('');
   console.log(chalk.bold.green('  ✅ All done!'));
   console.log('');
-  console.log(chalk.white('  Your AI workspace is ready at ') + chalk.cyan('.agent/'));
+  console.log(chalk.white('  Your AI workspace is ready:'));
   console.log('');
-  console.log(chalk.gray('  Structure:'));
-  console.log(chalk.gray('    .agent/'));
-  console.log(chalk.gray('    ├── settings.json       ← project config (commit this)'));
-  console.log(chalk.gray('    ├── settings.local.json ← local overrides (gitignored)'));
-  console.log(chalk.gray('    ├── rules/              ← agent rules'));
-  console.log(chalk.gray('    └── skills/             ← agent skills'));
+  console.log(chalk.gray('    AGENTS.md                       ← root agent instructions'));
+  console.log(chalk.gray('    .agents/'));
+  console.log(chalk.gray('    ├── settings.json               ← project config'));
+  console.log(chalk.gray('    ├── settings.local.json         ← local overrides (gitignored)'));
+  console.log(chalk.gray('    ├── commands/'));
+  console.log(chalk.gray('    │   ├── review.md               ← code review command'));
+  console.log(chalk.gray('    │   └── fix-issue.md            ← zero-error fix command'));
+  console.log(chalk.gray('    ├── skills/'));
+  console.log(chalk.gray('    └── rules/'));
   console.log('');
-  console.log(chalk.gray('  Edit the markdown files in .agent/ to customise agent behaviour.'));
-  console.log(chalk.gray('  Re-run ') + chalk.cyan('npx @p_tipso/agentive') + chalk.gray(' any time to re-sync to your AI tools.'));
+  console.log(chalk.gray('  Edit the markdown files to customise agent behaviour.'));
   console.log('');
 }
 

package/src/templates/AGENTS.md

@@ -0,0 +1,29 @@
+# Agent Instructions
+
+> This file is your project's top-level instruction file for AI agents.
+> It is generated by [agentive](https://github.com/TiPS0/agentive).
+
+## Project
+
+- **Name:** {{PROJECT_NAME}}
+
+## Agent Configuration
+
+All agent configuration lives inside the `.agents/` directory:
+
+| Path | Purpose |
+|------|---------|
+| `.agents/settings.json` | Project-wide agent configuration (commit this) |
+| `.agents/settings.local.json` | Local machine overrides (gitignored) |
+| `.agents/commands/` | Reusable prompt commands your agents can execute |
+| `.agents/skills/` | Skill definitions that teach agents how to behave |
+| `.agents/rules/` | Project-wide rules all agents must follow |
+
+## Getting Started
+
+1. Edit the markdown files inside `.agents/` to customise agent behaviour
+2. Add new commands in `.agents/commands/` for common tasks
+3. Add new skills in `.agents/skills/` to teach agents new capabilities
+4. Add new rules in `.agents/rules/` to enforce coding standards
+
+Re-run `npx @p_tipso/agentive` any time to re-sync changes to your AI tools.

package/src/templates/commands/README.md

@@ -0,0 +1,26 @@
+# Commands
+
+This folder contains **reusable prompt commands** — predefined instructions that AI agents can execute on demand.
+
+## How to use
+
+Each `.md` file in this directory is a command. To use a command, reference it by name when prompting your AI agent.
+
+## Structure
+
+Each command file should include:
+
+- **Goal:** What the command achieves
+- **Steps:** The ordered steps the agent should follow
+- **Output:** What the agent should produce at the end
+
+## Examples
+
+| File | Purpose |
+|------|---------|
+| `review.md` | Review code for bugs, performance, and best practices |
+| `fix-issue.md` | Diagnose and fix code errors with zero tolerance |
+
+## Adding new commands
+
+Create a new `.md` file in this folder. Name it clearly (e.g., `write-tests.md`, `refactor.md`, `deploy-check.md`).

package/src/templates/commands/fix-issue.md

@@ -0,0 +1,41 @@
+# Command: Fix Issue (Zero Code Error)
+
+> Use this command to diagnose and fix code errors with zero tolerance — no errors should remain after execution.
+
+## Goal
+
+Find and fix **all** code errors in the target file or project. The end result must compile, run, and pass all existing tests with zero errors.
+
+## Steps
+
+1. **Identify the error** — read the error message, stack trace, or failing test output
+2. **Locate the root cause** — trace the error to its origin (don't just fix the symptom)
+3. **Understand the context** — read surrounding code to understand the intended behaviour
+4. **Implement the fix** — make the minimal change that resolves the root cause
+5. **Check for side effects** — ensure the fix doesn't break other functionality
+6. **Verify** — confirm the error is resolved by running the relevant command or test
+
+## Rules
+
+- **Never** suppress or silence errors without fixing the underlying cause
+- **Never** add `// @ts-ignore`, `eslint-disable`, or similar without explicit approval
+- **Prefer** targeted fixes over large refactors
+- **Always** explain what caused the error and why the fix resolves it
+
+## Output
+
+```
+### Error
+[Original error message or description]
+
+### Root Cause
+[Explanation of why this error occurred]
+
+### Fix Applied
+[Description of what was changed and where]
+
+### Verification
+[How the fix was verified — command run, test passed, etc.]
+
+### Status: ✅ Resolved
+```

package/src/templates/commands/review.md

@@ -0,0 +1,37 @@
+# Command: Review Code
+
+> Use this command to perform a thorough code review on a file, folder, or pull request.
+
+## Goal
+
+Review the target code for correctness, performance, readability, and adherence to project conventions.
+
+## Steps
+
+1. **Read** the target code carefully from start to finish
+2. **Check for bugs** — logic errors, off-by-one errors, null/undefined handling, race conditions
+3. **Check for performance** — unnecessary re-renders, N+1 queries, missing indexes, memory leaks
+4. **Check for security** — injection vulnerabilities, exposed secrets, missing auth checks
+5. **Check for readability** — naming, function length, comment quality, dead code
+6. **Check for conventions** — does the code follow the rules defined in `.agents/rules/`?
+
+## Output
+
+Provide a structured review with:
+
+```
+### Summary
+One-sentence verdict (e.g., "Generally solid, 2 bugs found")
+
+### Issues Found
+- 🐛 **Bug:** [description] (file:line)
+- ⚡ **Performance:** [description] (file:line)
+- 🔒 **Security:** [description] (file:line)
+
+### Suggestions
+- 💡 [optional improvement]
+
+### Verdict
+- [ ] Ready to merge
+- [ ] Needs changes (see issues above)
+```

package/src/templates/rules/README.md

@@ -0,0 +1,29 @@
+# Rules
+
+This folder contains **project-wide rules** — constraints and standards that all AI agents must follow when working in this repository.
+
+## How to use
+
+Each `.md` file in this directory defines a set of rules. Agents will read and adhere to these rules for every task they perform.
+
+## Structure
+
+Each rule file should include:
+
+- **Purpose:** Why this rule exists
+- **Rules:** The specific constraints, listed clearly
+- **Examples:** Good vs. bad patterns (optional but recommended)
+
+## Examples of rules you could add
+
+| File | Purpose |
+|------|---------|
+| `code-style.md` | Naming conventions, formatting, and patterns |
+| `architecture.md` | How the project is structured, what goes where |
+| `testing.md` | Testing requirements, coverage expectations |
+| `security.md` | Security practices, data handling rules |
+| `git.md` | Branch naming, commit messages, PR conventions |
+
+## Adding new rules
+
+Create a new `.md` file in this folder. Name it after the topic (e.g., `error-handling.md`, `performance.md`).

package/src/templates/skills/README.md

@@ -0,0 +1,29 @@
+# Skills
+
+This folder contains **skill definitions** — instructions that teach AI agents how to behave in specific roles or capabilities.
+
+## How to use
+
+Each `.md` file in this directory defines a skill. The agent will adopt the role described in the skill file when activated.
+
+## Structure
+
+Each skill file should include:
+
+- **Role description:** What the agent does in this role
+- **Responsibilities:** Specific tasks the agent handles
+- **Inputs / Outputs:** What the agent expects and what it produces
+- **Constraints:** Boundaries the agent must respect
+
+## Examples of skills you could add
+
+| File | Purpose |
+|------|---------|
+| `web-browser.md` | How agents should browse the web and retrieve data |
+| `data-extractor.md` | How agents should extract structured data from raw content |
+| `code-writer.md` | How agents should write new code following project conventions |
+| `tester.md` | How agents should write and run tests |
+
+## Adding new skills
+
+Create a new `.md` file in this folder. Name it after the role (e.g., `api-designer.md`, `database-manager.md`).

package/src/utils/compilers.js

@@ -7,6 +7,7 @@ const path = require('path');
 
 /**
  * Read all .md files from a directory and return their concatenated content.
+ * Skips README.md files since those are directory documentation, not agent rules.
  * @param {string} dir
  * @returns {Promise<string>}
  */
@@ -15,7 +16,7 @@ async function readMarkdownDir(dir) {
   try {
     const entries = await fs.readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isFile() && entry.name.endsWith('.md')) {
+      if (entry.isFile() && entry.name.endsWith('.md') && entry.name !== 'README.md') {
         const filePath = path.join(dir, entry.name);
         const fileContent = await fs.readFile(filePath, 'utf-8');
         const section = entry.name.replace('.md', '').replace(/-/g, ' ');
@@ -57,12 +58,12 @@ async function copyDir(src, dest) {
 // ─── Cursor ──────────────────────────────────────────────────────────────────
 
 /**
- * Sync .agent/rules/ → .cursor/rules/
- * @param {string} agentDir
+ * Sync .agents/rules/ → .cursor/rules/
+ * @param {string} agentsDir
  * @param {string} cwd
  */
-async function syncToCursor(agentDir, cwd) {
-  const src  = path.join(agentDir, 'rules');
+async function syncToCursor(agentsDir, cwd) {
+  const src  = path.join(agentsDir, 'rules');
   const dest = path.join(cwd, '.cursor', 'rules');
   await copyDir(src, dest);
 }
@@ -70,19 +71,19 @@ async function syncToCursor(agentDir, cwd) {
 // ─── Claude ──────────────────────────────────────────────────────────────────
 
 /**
- * Compile .agent/ into a single CLAUDE.md file.
- * @param {string} agentDir
+ * Compile .agents/ into a single CLAUDE.md file.
+ * @param {string} agentsDir
  * @param {string} cwd
  * @param {string} techStack
  */
-async function syncToClaude(agentDir, cwd, techStack) {
-  const rulesContent  = await readMarkdownDir(path.join(agentDir, 'rules'));
-  const skillsContent = await readMarkdownDir(path.join(agentDir, 'skills'));
+async function syncToClaude(agentsDir, cwd, techStack) {
+  const rulesContent    = await readMarkdownDir(path.join(agentsDir, 'rules'));
+  const commandsContent = await readMarkdownDir(path.join(agentsDir, 'commands'));
 
   const claudeMd = `# CLAUDE.md — AI Agent Instructions
 
 > This file was auto-generated by [agentive](https://github.com/TiPS0/agentive).
-> Edit the source files in \`.agent/\` and re-run \`npx @p_tipso/agentive\` to regenerate.
+> Edit the source files in \`.agents/\` and re-run \`npx @p_tipso/agentive\` to regenerate.
 
 ## Project Context
 
@@ -91,8 +92,8 @@ async function syncToClaude(agentDir, cwd, techStack) {
 # Rules
 ${rulesContent}
 
-# Skills
-${skillsContent}
+# Commands
+${commandsContent}
 `.trim();
 
   await fs.writeFile(path.join(cwd, 'CLAUDE.md'), claudeMd, 'utf-8');
@@ -101,27 +102,27 @@ ${skillsContent}
 // ─── Windsurf ────────────────────────────────────────────────────────────────
 
 /**
- * Compile .agent/rules/ into a single .windsurfrules file.
- * @param {string} agentDir
+ * Compile .agents/rules/ into a single .windsurfrules file.
+ * @param {string} agentsDir
  * @param {string} cwd
  * @param {string} techStack
  */
-async function syncToWindsurf(agentDir, cwd, techStack) {
-  const rulesContent  = await readMarkdownDir(path.join(agentDir, 'rules'));
-  const skillsContent = await readMarkdownDir(path.join(agentDir, 'skills'));
+async function syncToWindsurf(agentsDir, cwd, techStack) {
+  const rulesContent    = await readMarkdownDir(path.join(agentsDir, 'rules'));
+  const commandsContent = await readMarkdownDir(path.join(agentsDir, 'commands'));
 
   const windsurfRules = `# .windsurfrules — AI Agent Instructions
 
 > Auto-generated by [agentive](https://github.com/TiPS0/agentive).
-> Edit \`.agent/\` and re-run \`npx @p_tipso/agentive\` to regenerate.
+> Edit \`.agents/\` and re-run \`npx @p_tipso/agentive\` to regenerate.
 
 **Tech Stack:** ${techStack}
 
 # Rules
 ${rulesContent}
 
-# Skills
-${skillsContent}
+# Commands
+${commandsContent}
 `.trim();
 
   await fs.writeFile(path.join(cwd, '.windsurfrules'), windsurfRules, 'utf-8');

package/src/utils/fileSystem.js

@@ -6,13 +6,13 @@ const path = require('path');
 // ─── Guards ──────────────────────────────────────────────────────────────────
 
 /**
- * Check if a .agent/ directory already exists in the given working directory.
+ * Check if a .agents/ directory already exists in the given working directory.
  * @param {string} cwd
  * @returns {Promise<boolean>}
  */
 async function agentDirectoryExists(cwd) {
   try {
-    await fs.access(path.join(cwd, '.agent'));
+    await fs.access(path.join(cwd, '.agents'));
     return true;
   } catch {
     return false;
@@ -22,57 +22,61 @@ async function agentDirectoryExists(cwd) {
 // ─── Directory Creation ───────────────────────────────────────────────────────
 
 /**
- * Create (or recreate) the .agent/ directory structure inside the user's project.
+ * Create (or recreate) the .agents/ directory structure inside the user's project.
  *
  * Structure:
- *   .agent/
+ *   AGENTS.md               ← project root
+ *   .agents/
  *   ├── settings.json
  *   ├── settings.local.json
- *   ├── rules/
- *   └── skills/
+ *   ├── commands/
+ *   ├── skills/
+ *   └── rules/
  *
  * @param {string} cwd - The user's current working directory
- * @param {boolean} overwrite - Whether to remove an existing .agent/ directory first
- * @returns {Promise<string>} The path to the created .agent/ directory
+ * @param {boolean} overwrite - Whether to remove an existing .agents/ directory first
+ * @returns {Promise<string>} The path to the created .agents/ directory
  */
 async function createAgentDirectory(cwd, overwrite = false) {
-  const agentDir = path.join(cwd, '.agent');
+  const agentsDir = path.join(cwd, '.agents');
 
   if (overwrite) {
-    await fs.rm(agentDir, { recursive: true, force: true });
+    await fs.rm(agentsDir, { recursive: true, force: true });
+    // Also remove old AGENTS.md if overwriting
+    try { await fs.rm(path.join(cwd, 'AGENTS.md'), { force: true }); } catch { /* noop */ }
   }
 
-  await fs.mkdir(agentDir, { recursive: true });
-  await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
-  await fs.mkdir(path.join(agentDir, 'skills'), { recursive: true });
+  await fs.mkdir(agentsDir, { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'commands'), { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'skills'), { recursive: true });
+  await fs.mkdir(path.join(agentsDir, 'rules'), { recursive: true });
 
-  return agentDir;
+  return agentsDir;
 }
 
 // ─── Settings Files ───────────────────────────────────────────────────────────
 
 /**
- * Write settings.json and settings.local.json inside .agent/.
+ * Write settings.json and settings.local.json inside .agents/.
  *
  * - settings.json        → tracked by git (project-wide config)
  * - settings.local.json  → gitignored (machine-specific overrides)
  *
- * Also appends `.agent/settings.local.json` to the project's .gitignore if one exists.
+ * Also appends `.agents/settings.local.json` to the project's .gitignore if one exists.
+ * Settings no longer include techStack or tools since the wizard was removed.
  *
- * @param {string} agentDir  - Absolute path to .agent/
+ * @param {string} agentsDir - Absolute path to .agents/
  * @param {object} settings  - The wizard answers to persist
  */
-async function writeSettings(agentDir, settings) {
+async function writeSettings(agentsDir, settings) {
   // settings.json — committed to git
   const settingsJson = {
     projectName:      settings.projectName,
-    techStack:        settings.techStack,
-    tools:            settings.tools,
     agentiveVersion:  settings.agentiveVersion,
     createdAt:        settings.createdAt,
   };
   await fs.writeFile(
-    path.join(agentDir, 'settings.json'),
+    path.join(agentsDir, 'settings.json'),
     JSON.stringify(settingsJson, null, 2) + '\n',
     'utf-8'
   );
@@ -83,17 +87,17 @@ async function writeSettings(agentDir, settings) {
     overrides: {},
   };
   await fs.writeFile(
-    path.join(agentDir, 'settings.local.json'),
+    path.join(agentsDir, 'settings.local.json'),
     JSON.stringify(localSettingsJson, null, 2) + '\n',
     'utf-8'
   );
 
   // Auto-append to .gitignore if it exists in cwd
-  const cwd = path.dirname(agentDir);
+  const cwd = path.dirname(agentsDir);
   const gitignorePath = path.join(cwd, '.gitignore');
   try {
     let gitignore = await fs.readFile(gitignorePath, 'utf-8');
-    const entry = '.agent/settings.local.json';
+    const entry = '.agents/settings.local.json';
     if (!gitignore.includes(entry)) {
       gitignore += `\n# Agentive local settings (machine-specific)\n${entry}\n`;
       await fs.writeFile(gitignorePath, gitignore, 'utf-8');
@@ -106,40 +110,63 @@ async function writeSettings(agentDir, settings) {
 // ─── Template Copying ─────────────────────────────────────────────────────────
 
 /**
- * Copy all template files from src/templates/ into the .agent/ directory.
- * Replaces {{TECH_STACK}} and {{YEAR}} placeholders in template files.
+ * Copy template files from src/templates/ into the user's project.
  *
- * Note: The context/ folder from templates is not copied (not part of .agent/ structure).
+ * - AGENTS.md → project root (cwd)
+ * - commands/, skills/, rules/ → .agents/
+ *
+ * Replaces {{PROJECT_NAME}} and {{YEAR}} placeholders.
  *
  * @param {string} templatesDir - Absolute path to src/templates/
- * @param {string} destDir      - Absolute path to .agent/
- * @param {string} techStack    - The user's tech stack string
+ * @param {string} agentsDir    - Absolute path to .agents/
+ * @param {string} projectName  - The user's project name
  */
-async function copyTemplates(templatesDir, destDir, techStack) {
-  // Only copy rules/ and skills/ — context/ is dropped from .agent/ structure
-  const foldersToInclude = ['rules', 'skills'];
+async function copyTemplates(templatesDir, agentsDir, projectName) {
+  const cwd = path.dirname(agentsDir);
+
+  // Copy AGENTS.md to project root
+  const agentMdSrc = path.join(templatesDir, 'AGENTS.md');
+  try {
+    let content = await fs.readFile(agentMdSrc, 'utf-8');
+    content = replacePlaceholders(content, projectName);
+    await fs.writeFile(path.join(cwd, 'AGENTS.md'), content, 'utf-8');
+  } catch { /* template may not exist */ }
 
+  // Copy folder templates into .agents/
+  const foldersToInclude = ['commands', 'skills', 'rules'];
   for (const folder of foldersToInclude) {
     const srcFolder = path.join(templatesDir, folder);
-    const destFolder = path.join(destDir, folder);
+    const destFolder = path.join(agentsDir, folder);
 
     try {
-      await fs.access(srcFolder); // skip if template folder doesn't exist
+      await fs.access(srcFolder);
     } catch {
       continue;
     }
 
-    await copyDirectoryRecursive(srcFolder, destFolder, techStack);
+    await copyDirectoryRecursive(srcFolder, destFolder, projectName);
   }
 }
 
+/**
+ * Replace template placeholders with actual values.
+ * @param {string} content
+ * @param {string} projectName
+ * @returns {string}
+ */
+function replacePlaceholders(content, projectName) {
+  return content
+    .replace(/\{\{PROJECT_NAME\}\}/g, projectName || '')
+    .replace(/\{\{YEAR\}\}/g, new Date().getFullYear().toString());
+}
+
 /**
  * Internal: recursively copies files from src to dest, replacing placeholders.
  * @param {string} src
  * @param {string} dest
- * @param {string} techStack
+ * @param {string} projectName
  */
-async function copyDirectoryRecursive(src, dest, techStack) {
+async function copyDirectoryRecursive(src, dest, projectName) {
   const entries = await fs.readdir(src, { withFileTypes: true });
 
   for (const entry of entries) {
@@ -148,12 +175,10 @@ async function copyDirectoryRecursive(src, dest, techStack) {
 
     if (entry.isDirectory()) {
       await fs.mkdir(destPath, { recursive: true });
-      await copyDirectoryRecursive(srcPath, destPath, techStack);
+      await copyDirectoryRecursive(srcPath, destPath, projectName);
     } else {
       let content = await fs.readFile(srcPath, 'utf-8');
-      content = content
-        .replace(/\{\{TECH_STACK\}\}/g, techStack)
-        .replace(/\{\{YEAR\}\}/g, new Date().getFullYear().toString());
+      content = replacePlaceholders(content, projectName);
       await fs.writeFile(destPath, content, 'utf-8');
     }
   }

package/src/templates/context/project_overview.md

@@ -1,62 +0,0 @@
-# Project Overview
-
-> This file provides essential context for AI agents working on this project.
-> Keep it updated as the project evolves.
-
-## About This Project
-
-<!-- Describe what this project does and who it is for -->
-
-**Tech Stack:** {{TECH_STACK}}
-
-## Project Goals
-
-<!-- List the primary goals and success criteria for this project -->
-
-1. 
-2. 
-3. 
-
-## Architecture Overview
-
-<!-- Briefly describe the high-level architecture and major components -->
-
-```
-your-project/
-├── src/           # Application source code
-├── tests/         # Test files
-└── docs/          # Documentation
-```
-
-## Key Conventions
-
-<!-- Document conventions that are unique to this project -->
-
-- **Branch naming**: `feat/`, `fix/`, `chore/` prefixes
-- **Commit messages**: Follow [Conventional Commits](https://www.conventionalcommits.org/)
-- **PR size**: Keep pull requests focused and under 400 lines changed
-
-## Important Files & Directories
-
-| Path | Purpose |
-|------|---------|
-| `src/` | Application source |
-| `.ai/` | Agent rules, skills, and context (source of truth) |
-
-## External Services & APIs
-
-<!-- List any external services, APIs, or integrations this project depends on -->
-
-| Service | Purpose | Docs |
-|---------|---------|------|
-| | | |
-
-## Known Gotchas
-
-<!-- Document non-obvious things that have caused bugs or confusion in the past -->
-
-- 
-
----
-
-*Generated by [agentive](https://github.com/TiPS0/agentive) on {{YEAR}}.*

package/src/templates/rules/architecture.md

@@ -1,42 +0,0 @@
-# Architecture Rules
-
-> These rules govern how AI agents should reason about, write, and modify code
-> in this project. All agents operating in this repository must follow them.
-
-## Tech Stack
-
-This project uses: **{{TECH_STACK}}**
-
-All generated code must be idiomatic for this stack and follow its established patterns.
-
-## Structural Principles
-
-- **Single Responsibility**: Every function, module, or class should do one thing well.
-- **Separation of Concerns**: Keep data fetching, business logic, and presentation in separate layers.
-- **DRY (Don't Repeat Yourself)**: Before adding new code, search for existing utilities or helpers.
-- **YAGNI (You Aren't Gonna Need It)**: Do not add features or abstractions that aren't required right now.
-
-## Code Style
-
-- Prefer **async/await** over raw Promises or callbacks.
-- Always handle errors explicitly — never swallow exceptions silently.
-- Use **descriptive, intent-revealing names** for variables, functions, and files.
-- Write **small, focused functions** (prefer < 30 lines per function).
-- Add **JSDoc or TSDoc comments** to all exported functions.
-
-## File Organisation
-
-- Group related code by **feature**, not by type (avoid giant `utils/` or `helpers/` dumping grounds).
-- Keep files focused — if a file grows past ~200 lines, consider splitting it.
-- Barrel exports (`index.js`) should only re-export, never contain logic.
-
-## Testing
-
-- Every new feature should have a corresponding test.
-- Test **behaviour**, not implementation details.
-- Prefer unit tests for pure functions; integration tests for side-effecting code.
-
-## Dependencies
-
-- Before adding a new dependency, consider if the task can be accomplished with built-ins.
-- Avoid dependencies with no active maintenance or that have known security advisories.

package/src/templates/skills/data-extractor.md

@@ -1,56 +0,0 @@
-# Skill: Data Extractor Agent
-
-> This skill defines how an AI agent should behave when its role is to
-> extract structured data from raw, unstructured, or semi-structured sources.
-
-## Role Description
-
-You are a **Data Extractor Agent**. Your job is to parse raw content (HTML, text,
-JSON, PDF, CSV, etc.) and extract specific, structured data points as defined by
-the schema provided by the orchestrator. You surface data — you do not transform
-or enrich it.
-
-## Responsibilities
-
-- Parse the provided raw content using the most appropriate method for its format.
-- Extract only the fields specified in the schema — do not add extra fields.
-- Return `null` for any field that cannot be found; do not guess or hallucinate values.
-- Normalise whitespace and remove HTML tags from text values.
-- Flag ambiguous or low-confidence extractions to the orchestrator.
-
-## Inputs
-
-| Input | Type | Description |
-|-------|------|-------------|
-| `content` | `string` | The raw content to parse |
-| `format` | `string` | One of: `html`, `text`, `json`, `csv`, `markdown` |
-| `schema` | `object` | JSON Schema defining the fields to extract |
-
-## Outputs
-
-```json
-{
-  "data": {
-    "field_name": "extracted value",
-    "another_field": null
-  },
-  "confidence": 0.95,
-  "warnings": ["Could not find 'phone_number' in source"]
-}
-```
-
-## Constraints
-
-- **Never infer** or fabricate a value that isn't explicitly present in the source.
-- **Always** include a `confidence` score between `0.0` and `1.0`.
-- If `confidence < 0.7`, always include a `warnings` entry explaining the uncertainty.
-- **Do not** make external network requests — work only with the content provided.
-
-## Error Handling
-
-| Error | Response |
-|-------|----------|
-| `Unsupported format` | Return an error; list supported formats |
-| `Schema mismatch` | Return partial data with warnings for missing fields |
-| `Empty content` | Return all fields as `null` with a warning |
-| `Parse error` | Report the specific parse error and return an empty `data` object |

package/src/templates/skills/data-transformer.md

@@ -1,62 +0,0 @@
-# Skill: Data Transformer Agent
-
-> This skill defines how an AI agent should behave when its role is to
-> clean, enrich, reformat, or restructure data from one schema to another.
-
-## Role Description
-
-You are a **Data Transformer Agent**. Your job is to take structured data
-produced by an extractor or another upstream agent and apply a set of
-transformation rules to produce a new, target schema. You bridge raw extracted
-data and the format needed by the output dispatcher or downstream system.
-
-## Responsibilities
-
-- Apply the transformation rules defined in the task to reshape input data.
-- Normalise dates to ISO 8601 format (`YYYY-MM-DDTHH:mm:ssZ`) unless told otherwise.
-- Normalise currency values to a base unit (e.g. cents) when dealing with financial data.
-- Deduplicate records when a `dedup_key` is specified.
-- Apply computed fields (e.g. `full_name = first_name + " " + last_name`).
-- Report rows/records that could not be transformed and explain why.
-
-## Inputs
-
-| Input | Type | Description |
-|-------|------|-------------|
-| `data` | `object \| array` | The raw structured data to transform |
-| `rules` | `object` | Transformation rules (field mappings, computed fields, filters) |
-| `target_schema` | `object` | The JSON Schema of the expected output |
-
-## Outputs
-
-```json
-{
-  "transformed": [
-    { "id": "abc-123", "full_name": "Ada Lovelace", "created_at": "1815-12-10T00:00:00Z" }
-  ],
-  "failed": [
-    { "record": { "raw": "..." }, "reason": "Missing required field: email" }
-  ],
-  "stats": {
-    "input_count": 10,
-    "success_count": 9,
-    "failed_count": 1
-  }
-}
-```
-
-## Constraints
-
-- **Do not** drop records silently — every failed transformation must appear in `failed`.
-- **Do not** make network requests to enrich data — use only what was provided.
-- **Preserve** the original data types unless an explicit cast is in the rules.
-- When a rule is ambiguous, apply the safest interpretation and add a warning.
-
-## Error Handling
-
-| Error | Response |
-|-------|----------|
-| `Invalid rule` | Report the specific rule that is invalid; skip that rule; continue with others |
-| `Schema violation` | Include the violating record in `failed` with the validation error |
-| `Empty input` | Return `{ transformed: [], failed: [], stats: { ... } }` immediately |
-| `Type mismatch` | Attempt a safe cast; if not possible, add the record to `failed` |

package/src/templates/skills/output-dispatcher.md

@@ -1,79 +0,0 @@
-# Skill: Output Dispatcher Agent
-
-> This skill defines how an AI agent should behave when its role is to
-> deliver final, processed data to one or more target destinations.
-
-## Role Description
-
-You are an **Output Dispatcher Agent**. Your job is to take the final,
-transformed data from an upstream agent and reliably deliver it to the
-specified destination(s). You are responsible for formatting, serialisation,
-and confirming successful delivery. You are the last step in the pipeline.
-
-## Responsibilities
-
-- Serialise data into the format required by the destination (`json`, `csv`, `markdown`, `plain text`, etc.).
-- Write to file, send to an API endpoint, or save to a database as instructed.
-- Confirm successful delivery and report the destination path or response.
-- Handle partial failures gracefully — report which destinations succeeded and which failed.
-- Never modify the data content — your job is delivery, not transformation.
-
-## Inputs
-
-| Input | Type | Description |
-|-------|------|-------------|
-| `data` | `object \| array` | The final data to deliver |
-| `destinations` | `array` | List of destination configs (see below) |
-| `format` | `string` | Output format: `json`, `csv`, `markdown`, `text` |
-
-### Destination Config Shape
-
-```json
-{
-  "type": "file",
-  "path": "./output/results.json"
-}
-```
-
-```json
-{
-  "type": "api",
-  "url": "https://api.example.com/results",
-  "method": "POST",
-  "headers": { "Authorization": "Bearer <token>" }
-}
-```
-
-## Outputs
-
-```json
-{
-  "results": [
-    { "destination": "./output/results.json", "status": "success", "bytes_written": 4096 },
-    { "destination": "https://api.example.com/results", "status": "failed", "error": "401 Unauthorized" }
-  ],
-  "summary": {
-    "total": 2,
-    "succeeded": 1,
-    "failed": 1
-  }
-}
-```
-
-## Constraints
-
-- **Do not** alter data content during serialisation — only change the representation.
-- **Always** report `status` for every destination, even on failure.
-- **Do not** retry automatically — report the failure and let the orchestrator decide.
-- Respect rate limits when dispatching to APIs — add delays if explicitly instructed.
-- **Never** log or store sensitive values (tokens, passwords) in the output.
-
-## Error Handling
-
-| Error | Response |
-|-------|----------|
-| `File write error` | Report the OS error; mark destination as `failed` |
-| `API 4xx` | Report status code and body; mark as `failed`; do not retry |
-| `API 5xx` | Report status code; mark as `failed`; note retry is possible |
-| `Invalid format` | Report the unsupported format; list supported formats |
-| `Network timeout` | Report timeout after 30 seconds; mark as `failed` |

package/src/templates/skills/web-browser.md

@@ -1,54 +0,0 @@
-# Skill: Web Browser Agent
-
-> This skill defines how an AI agent should behave when its role is to
-> browse the web, retrieve information, and interact with web pages.
-
-## Role Description
-
-You are a **Web Browser Agent**. Your job is to navigate the internet, retrieve
-accurate information from URLs, and return structured data to the orchestrator.
-You do not transform or interpret the data — you fetch and return it faithfully.
-
-## Responsibilities
-
-- Navigate to a given URL and retrieve its full page content.
-- Extract the visible text content, ignoring boilerplate (navbars, footers, ads).
-- Follow links within a domain when explicitly instructed to crawl.
-- Report the final resolved URL (after redirects) alongside the content.
-- Respect `robots.txt` and avoid rate-limiting target servers.
-
-## Inputs
-
-| Input | Type | Description |
-|-------|------|-------------|
-| `url` | `string` | The URL to navigate to |
-| `selector` | `string?` | Optional CSS selector to target specific content |
-| `follow_links` | `boolean?` | Whether to follow internal links (default: `false`) |
-
-## Outputs
-
-```json
-{
-  "url": "https://example.com/page",
-  "title": "Page Title",
-  "content": "Extracted text content...",
-  "links": ["https://example.com/related"],
-  "status": 200
-}
-```
-
-## Constraints
-
-- **Do not execute** scripts or interact with dynamic JavaScript unless using a headless browser tool.
-- **Do not** store credentials or session cookies beyond the current task.
-- **Always** return a `status` code and surface any HTTP errors to the orchestrator.
-- If a page returns a non-200 status, report the error and stop — do not retry without explicit instruction.
-
-## Error Handling
-
-| Error | Response |
-|-------|----------|
-| `404 Not Found` | Report to orchestrator; do not guess alternative URLs |
-| `403 Forbidden` | Report to orchestrator; do not attempt bypass |
-| `Timeout` | Retry once after 5 seconds; report failure if still unresponsive |
-| `Invalid URL` | Return an error immediately without making a network request |