agentfold 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francisco Hernandez
+
+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,197 @@
+# AgentFold
+
+Layered generator for AI agent configuration. Define guidance once, compose by profile, and output deterministic config files for Copilot, Codex, Cursor, and Claude Code.
+
+## Quickstart
+
+```bash
+# Initialise config hub (defaults to ~/.agentfold)
+npx agentfold init --targets codex,copilot
+
+# Apply to a project
+cd ~/code/my-project
+npx agentfold apply
+```
+
+This creates a config hub at `~/.agentfold` with a default profile and global layer, then renders target-specific files into the current project.
+
+## Architecture
+
+AgentFold is a **central configuration hub**. You author all layers, profiles, and tags in one place (`~/.agentfold` or `--config <path>`), then selectively apply generated output to any number of target projects.
+
+```
+~/.agentfold/            (config hub — one per user)
+  config/
+    profiles/            (profile definitions)
+    definitions/         (scope tags)
+  layers/
+    global/              (shared baseline)
+    team-x/              (team-specific content)
+    ...
+
+~/code/my-project/       (target project — receives output)
+  .github/               (Copilot output)
+  .codex/                (Codex output)
+  .agentfold/
+    manifest.json        (tracks managed files)
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Bootstrap config hub (default: `~/.agentfold`) |
+| `lint` | Validate profile and layers |
+| `build` | Render outputs to `<config>/out/` |
+| `diff` | Compare rendered vs project files |
+| `apply` | Write rendered files to project |
+| `status` | Show current config summary |
+| `doctor` | Health-check config hub and project |
+| `explain` | Trace why a content file is included/excluded |
+| `create-layer` | Scaffold a new layer directory |
+| `create-profile` | Create a new profile JSON |
+| `list-layers` | List available layers |
+| `list-profiles` | List available profiles |
+| `list-tags` | List allowed scope tags |
+| `add-tag` | Add a scope tag |
+| `delete-tag` | Remove a scope tag |
+| `add-rule` | Add a rule file to a layer |
+| `add-skill` | Add a skill directory to a layer |
+| `add-subagent` | Add a subagent file to a layer |
+| `add-command` | Add a command file to a layer |
+| `add-reference` | Add a reference file to a layer |
+
+Run `agentfold --help` for full flag reference.
+
+## How It Works
+
+1. **Layers** contain your canonical content: rules, skills, subagents, commands, references, MCP configs.
+2. **Profiles** define which layers to compose and which targets to generate (copilot, codex, cursor, claude).
+3. **Scope selectors** (tags + namespaces) on profiles filter content via frontmatter metadata.
+4. The **render pipeline** merges selected content by layer order and writes deterministic output files.
+
+### Layer Structure
+
+Each layer has 7 canonical folders:
+
+```
+layers/<name>/
+  agents/
+  commands/
+  mcp/
+  references/
+  rules/
+  skills/
+  subagents/
+```
+
+### Resolution
+
+All layers, profiles, and tags resolve from the **config hub** (`--config` or `~/.agentfold`):
+
+| Resource | Path |
+|----------|------|
+| Layers | `<config>/layers/<name>/` |
+| Profiles | `<config>/config/profiles/<name>.json` |
+| Tags | `<config>/config/definitions/scope-tags.json` |
+
+### Scope Filtering
+
+Content files use YAML frontmatter for scope metadata:
+
+```yaml
+---
+metadata:
+  scope:
+    namespace: team-name
+    tags:
+      - frontend
+      - testing
+---
+```
+
+Profile selectors filter by tags (`any`/`all` mode) and namespaces. Empty selectors include everything.
+
+## Typical Workflow
+
+```bash
+# 1. Bootstrap config hub
+agentfold init --targets codex,copilot
+
+# 2. Create a team layer and profile
+agentfold create-layer --name my-team
+agentfold create-profile --name dev --layers my-team --targets codex,copilot
+
+# 3. Add content to the layer via CLI
+agentfold add-rule --layer my-team --name code-review
+agentfold add-skill --layer my-team --name api-patterns
+agentfold add-subagent --layer my-team --name test-writer
+agentfold add-command --layer my-team --name run-checks
+
+# 4. Open the config hub to edit the generated boilerplate
+code ~/.agentfold      # VS Code
+cursor ~/.agentfold    # Cursor
+
+# 5. Apply to a project
+agentfold lint --profile dev --project ~/code/app
+agentfold apply --profile dev --project ~/code/app --prune
+
+# 6. Check status
+agentfold status --profile dev --project ~/code/app
+agentfold doctor --profile dev --project ~/code/app
+```
+
+Or specify a custom config hub:
+
+```bash
+agentfold init --config ~/my-config --targets codex
+agentfold apply --config ~/my-config --profile dev --project ~/code/app
+```
+
+## Editing the Config Hub
+
+To add or edit layers, rules, skills, and other content, open the config hub in your editor:
+
+```bash
+# Navigate to the default hub
+cd ~/.agentfold
+
+# Open in VS Code
+code ~/.agentfold
+
+# Open in Cursor
+cursor ~/.agentfold
+```
+
+From there you can edit files directly under `layers/`, create new profiles in `config/profiles/`, and manage tags in `config/definitions/`. Changes take effect the next time you run `agentfold apply`.
+
+## Generated Outputs
+
+| Target | Output |
+|--------|--------|
+| Copilot | `.github/instructions/`, `.github/prompts/`, `.github/agents/`, `.vscode/mcp.json` |
+| Codex | `.codex/AGENTS.md`, `.codex/config.toml` |
+| Cursor | `.cursor/rules/`, `.cursor/agents/`, `.cursor/mcp.json` |
+| Claude | `.claude/AGENTS.md`, `.claude/agents/` |
+| Portable | `.agents/skills/`, `.agents/subagents/`, `.agents/commands/`, `.agents/references/` |
+
+## Behavior Contracts
+
+- Layer order from `profile.layers` is authoritative.
+- Destination collisions fail fast with clear errors.
+- Deletions are manifest-scoped only (`.agentfold/manifest.json`).
+- Output ordering is deterministic (sorted traversal + hashing).
+- MCP configs are deep-merged per target from `layers/*/mcp/*.json`.
+- References are demand-driven: only files referenced in rendered content are included.
+
+## Development
+
+```bash
+npm test          # Run full test suite
+npm run lint      # Validate current profile
+npm run sync      # Lint + build + apply --prune
+```
+
+## License
+
+MIT