3 Commits

Author	SHA1	Message	Date
lh	f66f4f6566	Add Hey CLI as alternative email backend for Postman (#14) ... * Add Hey CLI support as alternative email backend The Postman agent now supports two email backends: - Hey (hey CLI) for Hey.com accounts with pre-sorted mailboxes - GWS (gws CLI) for Gmail/Google Workspace accounts Hey's mailbox model (Imbox, Feed, Paper Trail, Reply Later, Set Aside, Bubble Up) is mapped to triage behaviours so the agent leverages Hey's existing sorting. Calendar operations remain on GWS. All MCP function references replaced with CLI equivalents. No user-specific details in the agent file. * Update agents in postman.md by removing two roles Removed descriptions for Food Coach and Wellness Guide agents from the postman documentation. * Add Hey CLI as email backend across all docs, skills, and references - Resolve all merge conflicts in postman.md keeping GWS + MCP + Hey - Apply all 7 review comments from PR #14 (complete mailbox list, concrete email_backend setting, consistent template placeholders, Hey ID clarification, productivity features disclaimer, deadline body scanning, remove user-specific agent references) - Add Hey CLI alongside GWS/MCP in: README, CLAUDE.md, TERMS_OF_USE, DISCLAIMERS, getting-started, gws-setup-guide (renamed sections), agents-registry, agents.md, onboarding skill, launchme.sh - Update all 4 Postman-related skills (email-triage, deadline-radar, meeting-prep, weekly-agenda) with Hey CLI commands and backend detection - Expand security section to cover Hey CLI injection vectors - Keep MCP as read-only fallback for all backends * Address Copilot review: fix typos, injection rules, platform compat, install hooks - Fix hey imbox --json typo → hey box imbox --json - Fix after:{{yesterday}} → newer_than:2d for consistent 48h scan - Reconcile shell injection rules with hey reply/compose -m (user-approved text only, with safe quoting guidance) - Separate email write ops (GWS/Hey) from calendar write ops (GWS only) in TERMS_OF_USE and DISCLAIMERS - Replace grep -P with POSIX-compatible tab detection in validate-frontmatter - Add hooks/ and settings.json installation to launchme.sh and updateme.sh so .claude/hooks/ paths in settings.json resolve correctly --------- Co-authored-by: gnekt <dima9610@gmail.com>	2026-03-27 15:51:06 +01:00
lh	547fe06450	Replace MCP Gmail/Calendar with Google Workspace CLI (#9) ... * Replace MCP Gmail/Calendar with Google Workspace CLI Swap all MCP tool references (gmail_*, gcal_*) for gws CLI equivalents in the postman agent and all 4 postman-related skills. Add Bash to postman tools for gws execution. Include setup guide for gws installation and OAuth configuration. Addresses review feedback: Food Coach and Wellness Guide references removed (those agents no longer exist on main). * Update skills/weekly-agenda/SKILL.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Address Copilot review feedback - Add gmail.send scope to setup guide and agent docs - Use narrower calendar scopes (calendar.events + calendarlist.readonly) - Make gcloud optional in prerequisites - Fix .mcp.json example to remove only Gmail/Calendar entries - Split label modify into separate add/remove examples - Replace hard-coded dates with placeholders - Fix after:{{yesterday}} to newer_than:2d for 48h filtering - Update all docs/gws-setup-guide.md paths to repo-relative - Add MCP fallback note for users without gws - Add mandatory user confirmation before mark-read/archive actions * Fix PR review findings: add security guardrails and update all MCP references for gws dual-support - Add Security: External Content section to postman.md to prevent command injection from untrusted email content - Update agents-registry.md, agents.md, CLAUDE.md, README.md to reflect gws CLI + MCP fallback duality - Update TERMS_OF_USE.md and DISCLAIMERS.md legal text to mention gws alongside MCP - Update onboarding skill to present gws as recommended option with MCP as fallback - Fix placeholder in gws-setup-guide.md (was a raw template, now a concrete date) - Update agent-template.md to document Bash for CLI tool access pattern * Harden security for email/calendar operations and update legal coverage - Postman agent: comprehensive security section covering prompt injection, shell injection, write operation safeguards, and Bash command allowlist - All 4 postman-related skills: add security sections with prompt injection defense, shell injection rules, and explicit MCP fallback instructions - TERMS_OF_USE.md: new Section 4A covering risks from email/calendar read and write operations (adversarial content, unintended sends, deletions, calendar disruptions), updated Limitation of Liability section - DISCLAIMERS.md: new section explaining write operation risks in plain language, MCP as safer read-only alternative, and acknowledgment of prompt-based security limitations --------- Co-authored-by: gnekt <dima9610@gmail.com>	2026-03-26 18:41:04 +01:00
Gnekt	1ee2dc415f	Add custom agent system with orchestration, templates, and broadened legal coverage (#21) ... * Add standardized template for custom agent creation New file: references/agent-template.md This is a reference document that the Architect reads when generating custom agents. It defines the exact structure every agent must follow: YAML frontmatter format, required sections (Language, User Profile, Inter-Agent Coordination, Core Responsibilities, Operational Rules), placeholder tokens, and inline conventions (naming rules, tool permissions, multilingual triggers). The template is not an agent itself. It is a structural guide that ensures custom agents are generated with the same quality and consistency as the core 8. * Add custom agent support to orchestration references agents-registry.md: - Added "Custom Agents" section with rules for how custom agents are added to the registry (naming, priority, creation flow) - Custom agents always have lower priority than core 8 - Names must be lowercase with hyphens, no conflicts with core names agents.md: - Added "Custom Agents" section explaining what they are, how they coordinate with core agents, and how to create/edit/remove them agent-orchestration.md: - Added "Suggested new agent" signal format so agents can flag when the user needs functionality that no existing agent provides - Added step in Dispatcher Decision Logic to check for this signal - Added "Custom Agent Lifecycle" section covering creation, discovery, routing, chaining, maintenance, and deletion * Add "Suggested new agent" capability to all 7 non-architect agents Each agent now has a "When to suggest a new agent" subsection inside its Inter-Agent Coordination block. When an agent detects that the user needs functionality that no existing agent can handle, it outputs a "Suggested new agent" section with: - Need: what capability is missing - Reason: why no existing agent covers it - Suggested role: what the new agent would do The dispatcher reads this and asks the user if they want the Architect to create a custom agent for the detected need. Agents are also told when NOT to suggest a new agent (existing agent can handle it, one-off task, outside vault scope). * Add full custom agent creation flow to the Architect The Architect can now create, edit, and remove custom agents through an extended conversational flow with the user. Changes to the frontmatter: - Added trigger phrases for custom agent creation in 6 languages ("create a new agent", "custom agent", "crea un nuovo agente", etc.) New section "Custom Agent Creation" with: - 5-phase conversation flow (Understanding, Capabilities, Output, Advanced, Confirmation) where the Architect asks one question at a time and adapts follow-ups based on user answers - Agent file generation following references/agent-template.md - Automatic updates to agents-registry.md and agents.md - Management commands: edit, remove, list custom agents - Validation rules: no name conflicts with core 8, minimal tool permissions by default, mandatory coordination sections - Quality standards: Core Responsibilities must be detailed enough to produce a production-quality agent Also added the "Suggested new agent" subsection (same as other agents). * Update dispatcher routing to support custom agents - Changed "The ONLY agents you may use are these 8" to acknowledge that custom agents created by the Architect are also valid - Added row 9+ to the routing priority table for custom agents (always lower priority than core 8) - Added section 9 "CUSTOM AGENTS" with routing logic: when no core agent matches, check agents-registry.md for custom agents - Added check for "Suggested new agent" signals in the multi-agent routing decision flow (step 6) * Add custom agents to README, CONTRIBUTING, and TERMS_OF_USE README.md: - Badge changed from "8 Agents" to "8+ Agents" - Added custom agents as point 4 of "What makes this different", positioned right after the main pitch for maximum visibility - Includes a table of real-life scenarios (budget tracking, journaling, paper reading, project monitoring, client deadline management) - Links to Terms of Use for the responsibility disclaimer CONTRIBUTING.md: - Renamed "Propose a new crew member" to "Propose a new core crew member" with a note that users can create custom agents via Architect - Added "Custom agents vs. core agents" section explaining the distinction between personal custom agents and project-shipped core agents TERMS_OF_USE.md: - Added new Section 9 "Custom Agents" with full disclaimer: custom agents are entirely the user's creation and responsibility, no warranty on their behavior, author accepts no liability - Updated Section 7 (Limitation of Liability) to reference custom agents explicitly - Renumbered sections 9-11 to 10-12 * Force the Architect to always run the full conversation before creating a custom agent The Architect was generating custom agents immediately from a single user message instead of going through the 5-phase conversation flow. Added explicit blocking instructions at three points: - Section intro: "NEVER create an agent in one shot" - Before the conversation phases: "Do NOT generate the agent immediately, even if the request seems clear" - Explicit rule: "You are NOT allowed to create the agent file until Phase 5" - Reinforced one-question-per-message rule * Force custom agent descriptions to use only the user's language The Architect was copying the multilingual pattern from core agents and adding translations in 6+ languages to custom agent descriptions. Custom agents should have their description and trigger phrases written exclusively in the language the user speaks. Reinforced this rule in both the generation instructions and the validation rules section. * Force custom agent body to always be written in English The frontmatter description uses the user's language (for trigger matching), but the agent body (system prompt) must always be in English for better LLM instruction-following performance. The agent still responds in the user's language at runtime thanks to the language matching rule. * Add confirmation prompt before overwriting existing installation launchme.sh: - Detects if .claude/ or CLAUDE.md already exist in the vault - Shows the user what will be overwritten - Asks for explicit confirmation before proceeding - Clarifies that custom agents and vault notes are never touched updateme.sh: - Asks for confirmation before overwriting core files - Same clarification about custom agents being preserved * Deprecate removed files instead of leaving orphans in the vault When a file is removed from the repo (agents, references, or skills), the updater now renames it with a "-DEPRECATED" suffix and prepends a "DEPRECATED DO NOT USE" header instead of silently leaving it. updateme.sh: - Core agents in .claude/agents/ that no longer exist in the repo get renamed to {name}-DEPRECATED.md with deprecation header (custom agents are never touched) - References in .claude/references/ that no longer exist in the repo get the same treatment - The entire .claude/skills/ directory (removed from the project) gets renamed to .claude/skills-DEPRECATED/ with deprecation headers on each SKILL.md - Summary now reports deprecated file count launchme.sh: - Added confirmation prompt before overwriting existing installation - Skills generation and copying kept intact (generate-skills.py runs first, then copies to .claude/skills/) * Add first-run setup section to custom agent template and creation flow Custom agents now have a "First Run Setup" section that defines what the agent must do the very first time it is invoked: what questions to ask the user, what config files or folders to create, and how to detect that it has already been set up. agent-template.md: - New "First Run Setup" section between Core Responsibilities and Operational Rules, with subsections for detection, questions to ask, what to create, and post-setup behavior architect.md: - New Phase 4 "First Run Setup" in the conversational flow where the Architect asks the user what the agent should do on first run - Previous Phase 4 (Advanced) becomes Phase 5 - Previous Phase 5 (Confirmation) becomes Phase 6 - Updated blocking rules to reference Phase 6 * Redesign README header and broaden legal disclaimers for custom agents Improve README header visual hierarchy: centered title, prominent Discord CTA, metadata badges moved to secondary row. Replace two custom agent examples with funnier, gender-neutral ones. Rewrite TERMS_OF_USE Section 3 from "Health and Wellness Agents" to "Custom Agents and Advice-Generating Output" covering health, legal, financial, and all regulated domains. * Fix reference paths in architect to use .claude/references/ prefix The agent runs inside the vault where references live under .claude/references/, not under references/ (which is the repo layout). * Fix reference paths in agent-template to use .claude/references/ prefix * Add core-manifest to protect custom agents from deprecation launchme.sh and updateme.sh now write .core-manifest listing which agent files were installed as core. The deprecation loop checks this manifest before touching any file, so custom agents are never deprecated. * Skip agent deprecation if target DEPRECATED file already exists * Include skill count in updateme.sh summary condition and message * Fix agents-registry.md paths in CLAUDE.md to use .claude/references/ prefix * Add edit/remove/list trigger phrases to custom agent routing * Deprecate stale core agents on reinstall before copying new ones On reinstall (EXISTING=1), read the old .core-manifest and deprecate any agent that is no longer shipped in the repo, before writing the new manifest. Prevents stale core agents from lingering in the vault. * Fix custom agent description: triggers are in user's language, not multilingual * Fix updateme.sh: deprecate stale agents before rewriting manifest The manifest was being truncated and rewritten before the deprecation loop ran, so removed core agents were no longer in the manifest and got skipped as "custom". Now: read old manifest -> deprecate -> copy new agents -> rewrite manifest. * Fix grep exit code handling when removing last entry from manifest * Fix nested fenced code blocks in agent-template using tildes * Add core-manifest for references to protect user-created reference docs Same pattern as agents: launchme/updateme write a .core-manifest in .claude/references/ listing installed core files. The deprecation loop only touches files in the manifest, leaving user-created references untouched. * Move deprecated files to .claude/deprecated/ to prevent auto-discovery Deprecated agents kept in .claude/agents/ could still be auto-discovered by Claude Code via their frontmatter. Moving them to .claude/deprecated/ ensures they are completely invisible to the dispatcher while still preserved for user reference. * Harden updateme.sh from Copilot review feedback Address multiple issues raised during PR code review: - Skip deprecation entirely when .core-manifest is missing, preventing accidental deprecation of custom agents/references on first update - Preserve user's "## Custom Agents" sections in agents-registry.md and agents.md during reference updates (merge strategy instead of overwrite) - Update confirmation message to accurately reflect what is preserved * Preserve custom agent content during install and update - launchme.sh: skip overwriting agents-registry.md and agents.md on reinstall to preserve custom agent entries - updateme.sh: extract and re-insert custom table rows from the registry table plus custom sections, preventing data loss when updating from upstream - Require manifest before deprecating to avoid false positives * Update wardrobe-coach example phrase in README * Use robust string matching and printf for user-mutable refs - Replace grep -qw with bash substring match for filename detection - Replace echo with printf '%s\n' to prevent content mangling * Enforce step-by-step conversation in Architect and fix registry row reinsertion - Add HARD CONSTRAINT blocks to both onboarding and custom agent creation flows, forcing the use of AskUserQuestion for each question to prevent the Architect from skipping phases or bundling questions - Replace hard-coded "| postman |" match in updateme.sh with generic last-table-row detection to avoid breaking custom row reinsertion if core agents are renamed or reordered * Improve input handling in launchme.sh and updateme.sh for non-interactive shells * Extract 13 skills from agents and update full documentation Architecture change: complex multi-step flows (onboarding, email triage, transcription, etc.) are now skills that run in the main conversation context instead of agent subprocesses. This fixes the state/context loss that caused agents to skip phases during multi-turn conversations. Skills created (13): - Architect: /onboarding, /create-agent, /manage-agent, /defrag - Postman: /email-triage, /meeting-prep, /weekly-agenda, /deadline-radar - Transcriber: /transcribe - Librarian: /vault-audit, /deep-clean, /tag-garden - Sorter: /inbox-triage Agent changes: - architect.md: -70% (1554 → 473 lines) - transcriber.md: -72% (530 → 147 lines) - postman.md: -42%, librarian.md: -37%, sorter.md: -11% - All agents: explicit post-it create-if-not-exists Scripts: - launchme.sh/updateme.sh: copy skills/ directly, remove generate-skills.py Docs updated: - README.md: new Skills section, mermaid diagrams, routing - getting-started.md, examples.md: skill references - docs/agents/*.md: capability tables with skill vs agent routing - references/agents.md, agent-orchestration.md, agents-registry.md, agent-template.md: skill registry, skill-first routing protocol	2026-03-25 12:00:00 +01:00