delorenj · May 9, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026 · May 7, 2026
diff --git a/.gitignore b/.gitignore
@@ -21,6 +21,9 @@ dist/
 .env.local
 .env.*.local
 
+# Local Codex state and credentials
+.codex/
+
 # Operating System
 .DS_Store
 Thumbs.db
@@ -64,4 +67,5 @@ mcp-publisher
 # MCP Registry tokens (secrets)
 .mcpregistry_github_token
 .mcpregistry_registry_token
+.claude-flow/data/
 .claude-flow/metrics/**/*
diff --git a/README.md b/README.md
@@ -39,10 +39,41 @@ For a detailed list of changes, please refer to the [CHANGELOG.md](CHANGELOG.md)
 
 ## Installation
 
-This repository is designed as a **BMAD Skill Package**. 
-Install it as you would any normal BMAD skill by adding it to your `.agent/skills/` directory or installing it via your AI agent's skill management workflow.
+This repository is distributed as a **BMAD-compatible skill package** for the
+Trello MCP server. Install the `skill/` directory through your agent's skill
+management workflow, or place it in the agent's skills directory.
 
-When the skill is initialized by your agent, it will automatically run the bundled install script to set up the MCP server and build dependencies.
+When an agent activates the skill, it follows `skill/SKILL.md`. On first use,
+the agent runs the bundled installer:
+
+```bash
+bash skill/scripts/install.sh
+```
+
+The installer builds the MCP server from `skill/assets/source/` when Bun is
+available. If Bun is unavailable, it falls back to the published Smithery
+install path for `@delorenj/mcp-server-trello` and creates the same local
+`build/index.js` command path used by the skill activation check.
+
+## Skill package structure
+
+The skill is the agent-facing entry point for this repository.
+
+- `skill/SKILL.md`: Activation, routing, and agent workflow rules.
+- `skill/scripts/install.sh`: First-run installer for the bundled server.
+- `skill/references/trello-mcp/`: Focused references for setup, tools,
+  workflows, and gotchas.
+- `skill/assets/source/`: Bundled MCP server source used for local builds.
+
+For AI agents, start with `skill/SKILL.md` rather than this README. The README
+is the human-facing overview; the skill references are the operational surface
+for tool selection and Trello workflow rules.
+
+Maintainers can refresh the bundled source before packaging with:
+
+```bash
+mise run package
+```
 
 ## Configuration
 

diff --git a/_bmad-output/implementation-artifacts/1-1-initialize-skill-directory-structure.md b/_bmad-output/implementation-artifacts/1-1-initialize-skill-directory-structure.md
@@ -0,0 +1,60 @@
+# Story 1.1: Initialize skill directory structure
+
+Status: done
+
+## Story
+
+As a Trello MCP skill maintainer,
+I want a complete skill package directory structure,
+so that agents can load the skill and find install, source, and reference
+materials in predictable locations.
+
+## Acceptance Criteria
+
+1. The repository contains `skill/SKILL.md`.
+2. The repository contains `skill/scripts/install.sh`.
+3. The repository contains `skill/references/trello-mcp/`.
+4. The repository contains `skill/assets/source/` with bundled MCP server
+   source needed for a local build.
+5. The repository contains a repeatable packaging task to refresh the bundled
+   source.
+
+## Tasks / Subtasks
+
+- [x] Create the skill entry point.
+- [x] Create the installer directory and script.
+- [x] Create progressive-discovery reference directories.
+- [x] Bundle the server source under the skill assets directory.
+- [x] Add a packaging task that refreshes bundled source from repository files.
+
+## Dev Notes
+
+- Architecture requires a Cloudflare-style progressive-discovery layout:
+  `SKILL.md`, `scripts/`, `references/trello-mcp/`, and `assets/source/`.
+- No generated working files were saved to the repository root.
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/architecture.md#Revised Target
+  Architecture]
+- [Source: _bmad-output/planning-artifacts/epics.md#Story 1.1]
+
+## Dev Agent Record
+
+### Completion Notes List
+
+- Created the required skill package structure.
+- Bundled source files for self-contained installation.
+
+### File List
+
+- `skill/SKILL.md`
+- `skill/scripts/install.sh`
+- `skill/references/trello-mcp/README.md`
+- `skill/references/trello-mcp/configuration.md`
+- `skill/references/trello-mcp/api.md`
+- `skill/references/trello-mcp/patterns.md`
+- `skill/references/trello-mcp/gotchas.md`
+- `skill/assets/source/`
+- `scripts/build-skill-assets.sh`
+- `mise.toml`
diff --git a/_bmad-output/implementation-artifacts/1-2-create-skill-md-workflow.md b/_bmad-output/implementation-artifacts/1-2-create-skill-md-workflow.md
@@ -0,0 +1,49 @@
+# Story 1.2: Create SKILL.md workflow
+
+Status: done
+
+## Story
+
+As an AI agent using Trello,
+I want `SKILL.md` to route me to setup, API, workflow, and gotcha references,
+so that I can use the Trello MCP server without scanning unrelated files.
+
+## Acceptance Criteria
+
+1. `SKILL.md` has trigger-rich frontmatter for Trello MCP usage.
+2. `SKILL.md` documents first-run activation and install verification.
+3. `SKILL.md` points agents to focused reference files.
+4. `SKILL.md` groups tools by workflow capability.
+5. `SKILL.md` states agent rules for ID discovery, dates, rate limits, and
+   destructive actions.
+
+## Tasks / Subtasks
+
+- [x] Replace the minimal workflow with a progressive-discovery router.
+- [x] Document first-run activation against the local built server.
+- [x] Add tool routing groups for boards, cards, checklists, comments,
+  attachments, labels, members, and health.
+- [x] Add guardrails for dates, IDs, and Trello side effects.
+
+## Dev Notes
+
+- The frontmatter description is the primary skill-loading trigger, so it names
+  the main Trello domains explicitly.
+- The workflow uses reference files to keep `SKILL.md` compact while preserving
+  enough context for common operations.
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#3.3 Agent Workflow]
+- [Source: _bmad-output/planning-artifacts/architecture.md#Progressive
+  discovery architecture]
+
+## Dev Agent Record
+
+### Completion Notes List
+
+- Expanded `SKILL.md` into the agent-facing router and workflow guide.
+
+### File List
+
+- `skill/SKILL.md`
diff --git a/_bmad-output/implementation-artifacts/1-3-bundle-install-script.md b/_bmad-output/implementation-artifacts/1-3-bundle-install-script.md
@@ -0,0 +1,57 @@
+# Story 1.3: Bundle install script
+
+Status: done
+
+## Story
+
+As a skill user,
+I want the bundled install script to build the Trello MCP server from packaged
+source when possible,
+so that the skill works without depending on a live package registry at runtime.
+
+## Acceptance Criteria
+
+1. `skill/scripts/install.sh` is executable.
+2. The script builds from `skill/assets/source/` when Bun is available.
+3. The script falls back to the published package install path when Bun is not
+   available.
+4. The script prints the MCP command path and required environment variables.
+5. The script is safe to run multiple times.
+6. The bundled source includes the Smithery manifest used by the existing
+   distribution path.
+
+## Tasks / Subtasks
+
+- [x] Detect the skill root and bundled source directory.
+- [x] Copy source to a user data install directory.
+- [x] Install dependencies and build with Bun.
+- [x] Fall back to Smithery installation through `npx`.
+- [x] Print required Trello credential configuration.
+- [x] Include `smithery.yaml` in the source bundle.
+
+## Dev Notes
+
+- Runtime build output goes under
+  `{XDG_DATA_HOME:-$HOME/.local/share}/mcp-server-trello-skill/server`.
+- Re-running the script replaces the runtime install directory before rebuilding
+  from the bundled source.
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#3.2 First-Run
+  Installation]
+- [Source: _bmad-output/planning-artifacts/architecture.md#Build granularity
+  question]
+
+## Dev Agent Record
+
+### Completion Notes List
+
+- Reworked the installer from registry-first to bundled-source-first.
+
+### File List
+
+- `skill/scripts/install.sh`
+- `skill/assets/source/`
+- `scripts/build-skill-assets.sh`
+- `mise.toml`
diff --git a/_bmad-output/implementation-artifacts/1-4-update-documentation.md b/_bmad-output/implementation-artifacts/1-4-update-documentation.md
@@ -0,0 +1,44 @@
+# Story 1.4: Update documentation
+
+Status: done
+
+## Story
+
+As a repository reader,
+I want the README to describe this repository as a BMAD-compatible skill package,
+so that I understand how the skill and bundled MCP server fit together.
+
+## Acceptance Criteria
+
+1. The README identifies the repository as a BMAD-compatible skill package.
+2. Standalone-first installation language is replaced with skill installation
+   guidance.
+3. The README points agents to the skill entry point and references.
+4. Development instructions remain available for maintainers.
+
+## Tasks / Subtasks
+
+- [x] Update the installation section for skill-based installation.
+- [x] Add a skill package structure section.
+- [x] Preserve configuration and development guidance relevant to maintainers.
+
+## Dev Notes
+
+- The README remains human-facing. Agent-facing operational details live under
+  `skill/`.
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#3.4 Documentation]
+- [Source: _bmad-output/planning-artifacts/architecture.md#Documentation
+  dual-maintenance]
+
+## Dev Agent Record
+
+### Completion Notes List
+
+- Updated the README to reflect the skill package model.
+
+### File List
+
+- `README.md`
diff --git a/_bmad-output/implementation-artifacts/sprint-status.yaml b/_bmad-output/implementation-artifacts/sprint-status.yaml
@@ -1,14 +1,14 @@
 # generated: 2026-04-30T20:51:00
-# last_updated: 2026-04-30T20:51:00
+# last_updated: 2026-05-05T13:15:00
 # project: Trello MCP Skill Package
 # project_key: NOKEY
 # tracking_system: file-system
 # story_location: _bmad-output/implementation-artifacts/
 
 development_status:
-  epic-1: in-progress
-  1-1-initialize-skill-directory-structure: in-progress
-  1-2-create-skill-md-workflow: backlog
-  1-3-bundle-install-script: backlog
-  1-4-update-documentation: backlog
+  epic-1: done
+  1-1-initialize-skill-directory-structure: done
+  1-2-create-skill-md-workflow: done
+  1-3-bundle-install-script: done
+  1-4-update-documentation: done
   epic-1-retrospective: optional
diff --git a/mise.toml b/mise.toml
@@ -21,3 +21,14 @@ task = "link-agentfiles"
 [tasks.link-agentfiles]
 description = "Symlink all agent files to AGENTS.md"
 run = "{{config_root}}/.mise/scripts/link-agentfiles.sh"
+
+[tasks.package]
+description = "Refresh skill assets for packaging"
+run = "{{config_root}}/scripts/build-skill-assets.sh"
+
+[tasks.ci]
+description = "Run tests and refresh the skill source bundle"
+run = [
+  "npm run test",
+  "{{config_root}}/scripts/build-skill-assets.sh",
+]
diff --git a/scripts/build-skill-assets.sh b/scripts/build-skill-assets.sh
@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SOURCE_DIR="$ROOT_DIR/skill/assets/source"
+
+rm -rf "$SOURCE_DIR"
+mkdir -p "$SOURCE_DIR"
+
+cp -R "$ROOT_DIR/src" "$SOURCE_DIR/src"
+rm -f "$SOURCE_DIR/src/index.ts.backup"
+
+for file in package.json tsconfig.json bun.lock LICENSE smithery.yaml; do
+  if [ -f "$ROOT_DIR/$file" ]; then
+    cp "$ROOT_DIR/$file" "$SOURCE_DIR/$file"
+  fi
+done
+
+echo "Skill source bundle refreshed at skill/assets/source"