opencode-plugin-team-agreements 0.1.4 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## [0.2.1](https://github.com/jwilger/opencode-plugin-team-agreements/compare/opencode-plugin-team-agreements-v0.2.0...opencode-plugin-team-agreements-v0.2.1) (2026-01-23)
+
+
+### Features
+
+* Add comprehensive team agreements with project analysis and split document approach ([#16](https://github.com/jwilger/opencode-plugin-team-agreements/issues/16)) ([084edaa](https://github.com/jwilger/opencode-plugin-team-agreements/commit/084edaad210c23d6f25eaa64b09e730ba474d970))
+
+## [0.2.0](https://github.com/jwilger/opencode-plugin-team-agreements/compare/opencode-plugin-team-agreements-v0.1.4...opencode-plugin-team-agreements-v0.2.0) (2026-01-23)
+
+
+### ⚠ BREAKING CHANGES
+
+* Team agreements are now stored in AGENTS.md (or CLAUDE.md as fallback) in the project root instead of docs/TEAM_AGREEMENTS.md
+
+### Features
+
+* Use AGENTS.md for team agreements instead of docs/TEAM_AGREEMENTS.md ([#15](https://github.com/jwilger/opencode-plugin-team-agreements/issues/15)) ([00365ab](https://github.com/jwilger/opencode-plugin-team-agreements/commit/00365ab4d17f0cd4e22c2731f12fd6875d5b01e1))
+
+
+### Bug Fixes
+
+* Only export plugin function to prevent OpenCode crash ([#13](https://github.com/jwilger/opencode-plugin-team-agreements/issues/13)) ([d4f5930](https://github.com/jwilger/opencode-plugin-team-agreements/commit/d4f5930e0620d490b3fae635275130309f1fcfc0))
+
 ## [0.1.4](https://github.com/jwilger/opencode-plugin-team-agreements/compare/opencode-plugin-team-agreements-v0.1.3...opencode-plugin-team-agreements-v0.1.4) (2026-01-23)
 
 

package/README.md

@@ -4,18 +4,57 @@ An [OpenCode](https://opencode.ai) plugin that helps teams of humans and LLM age
 
 ## Features
 
-- **Interactive facilitation** - Guides teams through establishing agreements one topic at a time
-- **Core topics covered**:
-  - Storage location for agreements
-  - Programming languages and their purposes
-  - Code quality standards
-  - Commit message conventions
-  - Integration workflow (branching, PRs, CI)
-  - Testing requirements
-  - Amendment process for updating agreements
-- **Extensible** - Add custom topics beyond the core set
-- **Context injection** - Automatically injects agreements into LLM context at session start and after compaction
-- **Topic suggestions** - Users can suggest new standard topics via GitHub issues (using `gh` CLI)
+- **Comprehensive interview** - Covers 7 categories with ~22 topics for thorough team alignment
+- **Smart project analysis** - Detects languages, frameworks, CI, testing, AI tools to tailor questions
+- **Split document approach**:
+  - `docs/TEAM_AGREEMENTS.md` - Full reference documentation for humans
+  - `AGENTS.md` - Concise rules that LLMs need in context constantly
+- **Interactive facilitation** - Guides teams through one question at a time, allowing skips and pauses
+- **Enforcement setup** - Detects existing tooling and offers to set up automatic enforcement
+- **Context injection** - Automatically injects LLM-relevant rules after compaction
+- **Topic suggestions** - Suggest new standard topics via GitHub issues
+
+## Topics Covered
+
+### 1. Code & Quality
+- Programming Languages & Tech Stack
+- Code Quality Standards
+- Code Review Process
+- Testing Requirements
+
+### 2. Integration & Delivery
+- Version Control & Branching
+- Continuous Integration
+- Deployment & Release
+- Database & Schema Changes
+
+### 3. Operations & QA
+- Security Practices
+- Monitoring & Observability
+- Performance Standards
+- Accessibility & Internationalization
+
+### 4. Documentation & Knowledge
+- Documentation Standards
+- Architecture Decision Records (ADRs)
+- Dependency Management
+
+### 5. AI/LLM Collaboration
+- AI Tools & Policies
+- Autonomy Boundaries
+- AI Code Generation Standards
+- Context & Session Management
+- Human Oversight & Escalation
+- Learning & Improvement
+
+### 6. Team Process
+- Development Methodology
+- Planning & Work Breakdown
+- Communication & Collaboration
+
+### 7. Governance
+- Amendment Process
+- Open-Ended Topics
 
 ## Installation
 
@@ -36,26 +75,56 @@ Run the `/team-agreements` command in OpenCode:
 /team-agreements
 ```
 
-The plugin will guide you through establishing agreements for your project. You can also provide context:
+The plugin will first analyze your project and then guide you through establishing agreements. You can also provide context:
 
 ```
-/team-agreements I want to update our commit message conventions
+/team-agreements I want to update our AI collaboration policies
 ```
 
 ### Options when agreements exist
 
 If `docs/TEAM_AGREEMENTS.md` already exists, you'll be presented with options to:
 - **Review** - Display current agreements
-- **Amend** - Modify a specific section
-- **Start Over** - Begin fresh (with confirmation)
+- **Amend** - Modify specific sections
+- **Regenerate AGENTS.md** - Re-extract LLM-relevant rules
+
+### The split document approach
+
+This plugin creates two files with different purposes:
+
+**`docs/TEAM_AGREEMENTS.md`** - Comprehensive documentation including:
+- Complete code standards with examples
+- Full deployment and release procedures
+- On-call and incident processes
+- Meeting cadences and team ceremonies
+- Everything humans need for reference
+
+**`AGENTS.md`** - Only rules that affect day-to-day coding:
+- Code quality standards and patterns
+- Testing requirements
+- Commit message format
+- AI autonomy boundaries
+- Escalation triggers
+
+This split ensures LLM context isn't bloated with procedures they don't need constantly (deployment steps, post-mortem templates, etc.) while still giving humans complete documentation.
 
 ## How it works
 
-1. **Command registration** - The plugin registers the `/team-agreements` command via OpenCode's config hook
-2. **Interactive conversation** - An LLM guides you through each topic, asking one question at a time
-3. **Document generation** - Creates `docs/TEAM_AGREEMENTS.md` with your agreements
-4. **Auto-injection** - Adds agreements to the `instructions` config so all agents see them
-5. **Compaction handling** - Re-injects agreements after context compaction in long sessions
+1. **Project analysis** - Detects your tech stack, frameworks, CI/CD, and AI tools
+2. **Tailored interview** - Highlights relevant topics and suggests skippable ones
+3. **Interactive conversation** - One question at a time with trade-off discussions
+4. **Document generation** - Creates both `docs/TEAM_AGREEMENTS.md` and `AGENTS.md`
+5. **Enforcement detection** - Identifies existing tooling (ESLint, Prettier, Husky, etc.)
+6. **Enforcement setup** - Offers to configure automatic enforcement where possible
+7. **Compaction handling** - Re-injects AGENTS.md after context compaction
+
+## Tools provided
+
+The plugin registers these tools for LLM use:
+
+- `analyze_project` - Detects languages, frameworks, CI, testing, AI tools, and project characteristics
+- `detect_enforcement_mechanisms` - Finds existing linters, formatters, and CI workflows
+- `suggest_team_agreement_topic` - Files GitHub issues for new topic suggestions
 
 ## Suggesting new topics
 
@@ -78,6 +147,9 @@ npm install
 # Build
 npm run build
 
+# Run tests
+npm test
+
 # Watch mode for development
 npm run dev
 ```

package/dist/index.d.ts

@@ -1,54 +1,23 @@
-import { type Plugin } from "@opencode-ai/plugin";
-declare const PLUGIN_REPO = "jwilger/opencode-plugin-team-agreements";
-declare const COMMAND_TEMPLATE = "You are helping establish or review team agreements for this project. Team agreements define how humans and LLM agents collaborate on the codebase.\n\nUser's request: $ARGUMENTS\n\n## Instructions\n\n1. First, check if team agreements already exist at `docs/TEAM_AGREEMENTS.md`\n\n2. If agreements exist, present the user with options:\n   - **Review**: Display the current agreements\n   - **Amend**: Modify a specific section  \n   - **Start Over**: Begin fresh (with confirmation)\n\n3. If no agreements exist (or starting over), guide the user through establishing agreements one topic at a time. Start with these core topics:\n\n### Core Topics\n\n#### a. Storage Location\nAsk where team agreements should be stored. Suggest defaults:\n- Main file: `docs/TEAM_AGREEMENTS.md`\n- Supporting details: `docs/team_agreements/*.md`\n\n#### b. Programming Languages\n- What programming language(s) will be used in this project?\n- What is each language used for? (e.g., TypeScript for frontend, Rust for backend)\n- Are there specific versions or language-specific style guides to follow?\n\n#### c. Code Quality Standards\n- What does \"great code\" look like for this team?\n- How should we prioritize: readability vs. performance vs. simplicity?\n- Are there required patterns or anti-patterns to follow/avoid?\n- What about error handling conventions?\n- Naming conventions for files, functions, variables, types?\n\n#### d. Commit Message Conventions\n- What format should commit messages follow? (Conventional Commits, custom, freeform)\n- Are there required elements? (ticket numbers, scope, breaking change indicators)\n- Any rules on length, tense, capitalization?\n- Should commits be atomic (one logical change per commit)?\n\n#### e. Integration Workflow\n- Trunk-based development or feature branches?\n- Pull request requirements? (reviews, approvals, CI checks)\n- Who can merge to main/trunk?\n- What CI checks must pass before integration?\n- Any branch naming conventions?\n\n#### f. Testing Requirements\n- What testing is required before code is considered \"done\"?\n- Are there coverage thresholds?\n- What types of tests? (unit, integration, e2e, property-based)\n- When should tests be written? (TDD, after implementation, etc.)\n\n#### g. Amendment Process\n- How can these agreements be changed?\n- Who has authority to propose/approve changes?\n- What's the review/approval process for amendments?\n- How should changes be communicated to the team?\n\n4. For each topic:\n   - Ask ONE question at a time\n   - Discuss trade-offs when relevant\n   - Confirm understanding before moving on\n   - Record the team's decision clearly\n\n5. **After the core topics**, ask:\n   \"Are there any additional topics you'd like to establish agreements for?\"\n   \n   Suggest potential additional topics if helpful:\n   - **Architecture decisions** - How to document and track ADRs\n   - **Dependency management** - How to evaluate and approve new dependencies\n   - **Documentation standards** - What must be documented, where, in what format\n   - **LLM autonomy boundaries** - What can LLMs do without asking? What requires human approval?\n   - **Session handoff protocols** - How to summarize work for the next session/agent\n   - **Code review process** - What reviewers should look for, turnaround expectations\n   - **Planning and work breakdown** - How to break down work into tasks\n   - **Information sharing** - How to share context across sessions and team members\n   \n   Continue asking about each additional topic the user wants to cover.\n   \n   After discussing additional topics, ask: \"Would you like to suggest any of these additional topics\n   (or others you thought of) to be included as standard topics in the team-agreements plugin?\n   I can file a GitHub issue for you if you'd like.\"\n   \n   If the user wants to suggest a topic, use the `suggest_team_agreement_topic` tool to file an issue.\n\n6. After ALL topics (core + additional) are covered:\n   - Generate `docs/TEAM_AGREEMENTS.md` with all agreements organized by topic\n   - If any topic needs detailed documentation, create supporting files in `docs/team_agreements/`\n   - Update `opencode.json` to include `docs/TEAM_AGREEMENTS.md` in the `instructions` array\n   - Summarize what was established\n\n7. **After generating the agreements**, use the `detect_enforcement_mechanisms` tool to check what enforcement is already in place, then offer to set up automatic enforcement for agreements that can be enforced programmatically.\n\n   For each agreement that CAN be automatically enforced, ask the user if they'd like help setting it up. Here are the enforcement mechanisms to consider:\n\n   ### Enforcement Mechanisms\n\n   #### OpenCode Plugin Hooks\n   Ideal for: LLM behavior guidance, context injection, custom commands\n   - Can add validation in `tool.execute.before` hooks\n   - Can transform messages via `experimental.chat.messages.transform`\n   - Can inject reminders in `experimental.session.compacting`\n\n   #### Pre-commit Hooks (husky, lefthook, pre-commit)\n   Ideal for: Commit message validation, code formatting, linting, test execution\n   - **Commit messages**: Use commitlint with husky for Conventional Commits or custom formats\n   - **Code formatting**: Run prettier/eslint/biome on staged files\n   - **Tests**: Run affected tests before allowing commits\n   - **File restrictions**: Prevent commits to certain paths\n\n   #### CI Workflows (GitHub Actions, etc.)\n   Ideal for: Test coverage, build verification, security scanning, PR checks\n   - **Testing requirements**: Enforce coverage thresholds, run full test suites\n   - **Code quality**: Run linters, type checking, security audits\n   - **Build verification**: Ensure the project builds successfully\n   - **PR requirements**: Block merging until checks pass\n\n   #### GitHub Rulesets / Branch Protection\n   Ideal for: PR requirements, review policies, merge restrictions\n   - **Required reviews**: Set minimum approvals before merge\n   - **Required checks**: Specify which CI checks must pass\n   - **Branch restrictions**: Control who can push to main/protected branches\n   - **Commit signing**: Require verified commits\n\n   #### Linting Rules (.eslintrc, biome.json, etc.)\n   Ideal for: Code style, naming conventions, import organization, complexity limits\n   - **Naming conventions**: Enforce variable/function/file naming patterns\n   - **Code patterns**: Require/forbid certain coding patterns\n   - **Import organization**: Enforce import ordering and restrictions\n\n   ### Mapping Agreements to Enforcement\n\n   | Agreement Topic | Possible Enforcement |\n   |-----------------|---------------------|\n   | Commit message conventions | commitlint + husky, GitHub Actions check |\n   | Code quality standards | ESLint/Biome rules, pre-commit hooks, CI checks |\n   | Testing requirements | CI workflow with coverage thresholds, pre-commit test runs |\n   | Integration workflow | GitHub rulesets, required status checks, PR templates |\n   | Programming language standards | Language-specific linters, compiler flags |\n\n   ### When Offering Enforcement\n\n   - Only offer enforcement for agreements that can actually be automated\n   - Explain what the enforcement will do and how it works\n   - Get explicit confirmation before making changes\n   - If enforcement tooling already exists (detected by the tool), offer to update/extend it rather than replace it\n   - Document what enforcement was set up in the TEAM_AGREEMENTS.md file\n\n## Output Format\n\nWhen generating the TEAM_AGREEMENTS.md file, use this structure:\n\n```markdown\n# Team Agreements\n\nThis document defines how our team (humans and LLM agents) collaborates on this codebase.\n\n## Table of Contents\n[Generate based on topics covered]\n\n## 1. Storage Location\n[Agreements about where documentation lives]\n\n## 2. Programming Languages\n[Agreements about languages and their usage]\n\n## 3. Code Quality Standards\n[Agreements about what makes good code]\n\n## 4. Commit Message Conventions\n[Agreements about commit message format]\n\n## 5. Integration Workflow\n[Agreements about how code gets integrated]\n\n## 6. Testing Requirements\n[Agreements about testing]\n\n## 7. Amendment Process\n[Agreements about changing these agreements]\n\n## Additional Topics\n[Any additional topics the team added]\n\n---\n*Last updated: [date]*\n*To amend these agreements, [process from amendment section]*\n```\n\n## Important\n\n- Be conversational and collaborative\n- ONE question at a time - don't overwhelm\n- Respect the user's expertise and preferences\n- If the user provides a specific request in their message, address that first\n- The core topics are a starting point, not an exhaustive list\n- Capture the \"why\" behind decisions, not just the \"what\"";
-/**
- * Check if a file exists at the given path.
- */
-export declare function fileExists(path: string): Promise<boolean>;
-/**
- * Check if the gh CLI is installed and authenticated.
- */
-export declare function isGhAvailable(): Promise<boolean>;
-/**
- * Load team agreements from the project directory.
- * Returns the content if found, null otherwise.
- */
-export declare function loadTeamAgreements(directory: string): Promise<string | null>;
-/**
- * Format suggested questions as a markdown list.
- */
-export declare function formatQuestionsAsMarkdown(questions: string[]): string;
-/**
- * Build the issue body for a topic suggestion.
- */
-export declare function buildTopicIssueBody(args: {
-    topic_name: string;
-    description: string;
-    suggested_questions: string[];
-    example_agreement?: string;
-}): string;
-/**
- * Enforcement mechanism detection result.
- */
-export interface EnforcementMechanism {
-    type: string;
-    name: string;
-    detected: boolean;
-    configFile?: string;
-    notes?: string;
-}
-/**
- * Detect existing enforcement mechanisms in the project.
- */
-export declare function detectEnforcementMechanisms(directory: string): Promise<EnforcementMechanism[]>;
 /**
- * Format enforcement detection results as markdown.
+ * OpenCode Team Agreements Plugin
+ *
+ * Helps teams establish and maintain shared agreements for human-LLM collaboration.
+ *
+ * IMPORTANT: Only the plugin function should be exported from this module.
+ * OpenCode's plugin loader iterates through all exports and tries to call each
+ * one as a plugin function. Exporting non-function values (like strings or objects)
+ * will cause a crash.
+ *
+ * @packageDocumentation
  */
-export declare function formatEnforcementResults(mechanisms: EnforcementMechanism[]): string;
-export { COMMAND_TEMPLATE, PLUGIN_REPO };
+import { type Plugin } from "@opencode-ai/plugin";
 /**
  * TeamAgreementsPlugin - Helps teams establish and maintain shared agreements
  * for human-LLM collaboration on a codebase.
+ *
+ * Team agreements are stored in AGENTS.md (or CLAUDE.md as fallback) in the
+ * project root. These files are automatically loaded by OpenCode and Claude Code,
+ * so no config injection is needed.
  */
 export declare const TeamAgreementsPlugin: Plugin;
 export default TeamAgreementsPlugin;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,qBAAqB,CAAA;AAQvD,QAAA,MAAM,WAAW,4CAA4C,CAAA;AAE7D,QAAA,MAAM,gBAAgB,4pRAqMoC,CAAA;AAE1D;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAO/D;AAED;;GAEG;AACH,wBAAsB,aAAa,IAAI,OAAO,CAAC,OAAO,CAAC,CAOtD;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CASlF;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAErE;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE;IACxC,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,EAAE,MAAM,EAAE,CAAA;IAC7B,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B,GAAG,MAAM,CAiBT;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,OAAO,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;GAEG;AACH,wBAAsB,2BAA2B,CAC/C,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,oBAAoB,EAAE,CAAC,CA2LjC;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,UAAU,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAkEnF;AAGD,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,CAAA;AAExC;;;GAGG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAmHlC,CAAA;AAED,eAAe,oBAAoB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,qBAAqB,CAAA;AAevD;;;;;;;GAOG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAwHlC,CAAA;AAED,eAAe,oBAAoB,CAAA"}