@p_tipso/agentive 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pakawat Tipso
+
+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,127 @@
+<![CDATA[<div align="center">
+
+# 🤖 agentive
+
+**A universal, framework-agnostic AI agent workspace CLI.**
+
+[![npm version](https://img.shields.io/npm/v/@p_tipso/agentive.svg?style=flat-square)](https://www.npmjs.com/package/@p_tipso/agentive)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square)](https://nodejs.org)
+
+</div>
+
+---
+
+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.
+
+## ✨ 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
+
+```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)
+
+Then it scaffolds everything automatically.
+
+---
+
+## 📁 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
+```
+
+### `settings.json` example
+
+```json
+{
+  "projectName": "my-app",
+  "techStack": "Next.js, TypeScript, PostgreSQL",
+  "tools": ["cursor", "claude"],
+  "agentiveVersion": "1.0.0",
+  "createdAt": "2026-07-05T12:00:00.000Z"
+}
+```
+
+---
+
+## 📦 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 --version` | Print the current version |
+| `npx @p_tipso/agentive --help` | Show available commands |
+
+---
+
+## 🛠 Install Globally (optional)
+
+If you use this frequently, install it globally:
+
+```bash
+npm install -g @p_tipso/agentive
+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)
+2. Clone your fork
+3. `npm install`
+4. `npm link` (to use `agentive` locally while developing)
+5. Make your changes and open a pull request!
+
+---
+
+## 📄 License
+
+MIT © [Pakawat Tipso](https://github.com/TiPS0)
+]]>

package/bin/index.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const { Command } = require('commander');
+const { version } = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('agentive')
+  .description('Universal AI agent workspace setup CLI')
+  .version(version, '-v, --version', 'Print the current version');
+
+program
+  .command('init', { isDefault: true })
+  .description('Initialize a universal .agent/ workspace in your project')
+  .action(async () => {
+    const { runInit } = require('../src/commands/init');
+    await runInit();
+  });
+
+program.parse(process.argv);

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@p_tipso/agentive",
+  "version": "1.0.0",
+  "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",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "agentive": "bin/index.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "ai",
+    "agent",
+    "cli",
+    "cursor",
+    "claude",
+    "windsurf",
+    "scaffold",
+    "init",
+    "rules",
+    "context"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TiPS0/agentive.git"
+  },
+  "homepage": "https://github.com/TiPS0/agentive#readme",
+  "bugs": {
+    "url": "https://github.com/TiPS0/agentive/issues"
+  },
+  "scripts": {
+    "prepare": "node -e \"console.log('agentive ready.')\"",
+    "test": "node bin/index.js --version"
+  },
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^12.1.0",
+    "prompts": "^2.4.2"
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const path = require('path');
+const prompts = require('prompts');
+const chalk = require('chalk');
+const { version } = require('../../package.json');
+const {
+  createAgentDirectory,
+  copyTemplates,
+  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();
+
+  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 ---
+  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);
+    }
+  }
+
+  // --- 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('');
+
+  // --- Scaffold .agent/ directory ---
+  const templatesDir = path.join(__dirname, '..', 'templates');
+  const agentDir = await createAgentDirectory(cwd, alreadyExists);
+  await copyTemplates(templatesDir, agentDir, techStack);
+
+  // --- Write settings.json and settings.local.json ---
+  await writeSettings(agentDir, {
+    projectName: finalProjectName,
+    techStack,
+    tools,
+    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));
+    }
+  }
+
+  // --- 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('');
+  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('');
+  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('');
+}
+
+module.exports = { runInit };

package/src/templates/context/project_overview.md

@@ -0,0 +1,62 @@
+# 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

@@ -0,0 +1,42 @@
+# 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

@@ -0,0 +1,56 @@
+# 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

@@ -0,0 +1,62 @@
+# 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

@@ -0,0 +1,79 @@
+# 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

@@ -0,0 +1,54 @@
+# 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 |

package/src/utils/compilers.js

@@ -0,0 +1,130 @@
+'use strict';
+
+const fs = require('fs/promises');
+const path = require('path');
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/**
+ * Read all .md files from a directory and return their concatenated content.
+ * @param {string} dir
+ * @returns {Promise<string>}
+ */
+async function readMarkdownDir(dir) {
+  let content = '';
+  try {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && entry.name.endsWith('.md')) {
+        const filePath = path.join(dir, entry.name);
+        const fileContent = await fs.readFile(filePath, 'utf-8');
+        const section = entry.name.replace('.md', '').replace(/-/g, ' ');
+        content += `\n## ${section}\n\n${fileContent}\n\n---\n`;
+      }
+    }
+  } catch {
+    // Directory may not exist; silently skip
+  }
+  return content;
+}
+
+/**
+ * Ensure a directory exists, creating it if necessary.
+ * @param {string} dirPath
+ */
+async function ensureDir(dirPath) {
+  await fs.mkdir(dirPath, { recursive: true });
+}
+
+/**
+ * Copy all files from a source directory to a destination directory.
+ * @param {string} src
+ * @param {string} dest
+ */
+async function copyDir(src, dest) {
+  await ensureDir(dest);
+  const entries = await fs.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isFile()) {
+      await fs.copyFile(
+        path.join(src, entry.name),
+        path.join(dest, entry.name)
+      );
+    }
+  }
+}
+
+// ─── Cursor ──────────────────────────────────────────────────────────────────
+
+/**
+ * Sync .agent/rules/ → .cursor/rules/
+ * @param {string} agentDir
+ * @param {string} cwd
+ */
+async function syncToCursor(agentDir, cwd) {
+  const src  = path.join(agentDir, 'rules');
+  const dest = path.join(cwd, '.cursor', 'rules');
+  await copyDir(src, dest);
+}
+
+// ─── Claude ──────────────────────────────────────────────────────────────────
+
+/**
+ * Compile .agent/ into a single CLAUDE.md file.
+ * @param {string} agentDir
+ * @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'));
+
+  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.
+
+## Project Context
+
+**Tech Stack:** ${techStack}
+
+# Rules
+${rulesContent}
+
+# Skills
+${skillsContent}
+`.trim();
+
+  await fs.writeFile(path.join(cwd, 'CLAUDE.md'), claudeMd, 'utf-8');
+}
+
+// ─── Windsurf ────────────────────────────────────────────────────────────────
+
+/**
+ * Compile .agent/rules/ into a single .windsurfrules file.
+ * @param {string} agentDir
+ * @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'));
+
+  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.
+
+**Tech Stack:** ${techStack}
+
+# Rules
+${rulesContent}
+
+# Skills
+${skillsContent}
+`.trim();
+
+  await fs.writeFile(path.join(cwd, '.windsurfrules'), windsurfRules, 'utf-8');
+}
+
+module.exports = { syncToCursor, syncToClaude, syncToWindsurf };

package/src/utils/fileSystem.js

@@ -0,0 +1,167 @@
+'use strict';
+
+const fs = require('fs/promises');
+const path = require('path');
+
+// ─── Guards ──────────────────────────────────────────────────────────────────
+
+/**
+ * Check if a .agent/ 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'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Directory Creation ───────────────────────────────────────────────────────
+
+/**
+ * Create (or recreate) the .agent/ directory structure inside the user's project.
+ *
+ * Structure:
+ *   .agent/
+ *   ├── settings.json
+ *   ├── settings.local.json
+ *   ├── rules/
+ *   └── skills/
+ *
+ * @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
+ */
+async function createAgentDirectory(cwd, overwrite = false) {
+  const agentDir = path.join(cwd, '.agent');
+
+  if (overwrite) {
+    await fs.rm(agentDir, { recursive: true, force: true });
+  }
+
+  await fs.mkdir(agentDir, { recursive: true });
+  await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
+  await fs.mkdir(path.join(agentDir, 'skills'), { recursive: true });
+
+  return agentDir;
+}
+
+// ─── Settings Files ───────────────────────────────────────────────────────────
+
+/**
+ * Write settings.json and settings.local.json inside .agent/.
+ *
+ * - 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.
+ *
+ * @param {string} agentDir  - Absolute path to .agent/
+ * @param {object} settings  - The wizard answers to persist
+ */
+async function writeSettings(agentDir, 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'),
+    JSON.stringify(settingsJson, null, 2) + '\n',
+    'utf-8'
+  );
+
+  // settings.local.json — NOT committed (machine-specific overrides)
+  const localSettingsJson = {
+    _note: 'This file is gitignored. Add local machine-specific overrides here.',
+    overrides: {},
+  };
+  await fs.writeFile(
+    path.join(agentDir, '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 gitignorePath = path.join(cwd, '.gitignore');
+  try {
+    let gitignore = await fs.readFile(gitignorePath, 'utf-8');
+    const entry = '.agent/settings.local.json';
+    if (!gitignore.includes(entry)) {
+      gitignore += `\n# Agentive local settings (machine-specific)\n${entry}\n`;
+      await fs.writeFile(gitignorePath, gitignore, 'utf-8');
+    }
+  } catch {
+    // No .gitignore present — silently skip
+  }
+}
+
+// ─── Template Copying ─────────────────────────────────────────────────────────
+
+/**
+ * Copy all template files from src/templates/ into the .agent/ directory.
+ * Replaces {{TECH_STACK}} and {{YEAR}} placeholders in template files.
+ *
+ * Note: The context/ folder from templates is not copied (not part of .agent/ structure).
+ *
+ * @param {string} templatesDir - Absolute path to src/templates/
+ * @param {string} destDir      - Absolute path to .agent/
+ * @param {string} techStack    - The user's tech stack string
+ */
+async function copyTemplates(templatesDir, destDir, techStack) {
+  // Only copy rules/ and skills/ — context/ is dropped from .agent/ structure
+  const foldersToInclude = ['rules', 'skills'];
+
+  for (const folder of foldersToInclude) {
+    const srcFolder = path.join(templatesDir, folder);
+    const destFolder = path.join(destDir, folder);
+
+    try {
+      await fs.access(srcFolder); // skip if template folder doesn't exist
+    } catch {
+      continue;
+    }
+
+    await copyDirectoryRecursive(srcFolder, destFolder, techStack);
+  }
+}
+
+/**
+ * Internal: recursively copies files from src to dest, replacing placeholders.
+ * @param {string} src
+ * @param {string} dest
+ * @param {string} techStack
+ */
+async function copyDirectoryRecursive(src, dest, techStack) {
+  const entries = await fs.readdir(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()) {
+      await fs.mkdir(destPath, { recursive: true });
+      await copyDirectoryRecursive(srcPath, destPath, techStack);
+    } else {
+      let content = await fs.readFile(srcPath, 'utf-8');
+      content = content
+        .replace(/\{\{TECH_STACK\}\}/g, techStack)
+        .replace(/\{\{YEAR\}\}/g, new Date().getFullYear().toString());
+      await fs.writeFile(destPath, content, 'utf-8');
+    }
+  }
+}
+
+module.exports = {
+  agentDirectoryExists,
+  createAgentDirectory,
+  writeSettings,
+  copyTemplates,
+};