feat: feat: replace rules with instructions content type#27
Merged
mfaux merged 9 commits intoApr 3, 2026
Conversation
Add the instruction content type to the type system and implement a parser for INSTRUCTIONS.md files. This is the foundation for replacing rules with instructions as the primary agent context mechanism. - Add 'instruction' to ContextType union - Create CanonicalInstruction interface and InstructionOverrideFields type - Implement parseInstructionContent() with gray-matter frontmatter extraction, field validation, and description-only per-agent overrides - Add comprehensive tests for parsing, validation, overrides, and edge cases
Add per-agent instruction transpilers that convert CanonicalInstruction into marker-based append content for each target agent's project-wide instruction file. Implement output-path deduplication so Cursor and OpenCode (both targeting AGENTS.md) produce only one write. - Add InstructionsConfig type and instructionsConfig to TargetAgentConfig - Configure all 4 agents: Copilot → .github/copilot-instructions.md, Claude Code → CLAUDE.md, Cursor → AGENTS.md, OpenCode → AGENTS.md - Update getOutputDir() to handle 'instruction' context type - Create instruction-transpilers.ts with transpiler registry, per-agent transpilers, override merging, and output-path deduplication - Add 48 tests covering all agents, deduplication, overrides, and edges Closes #19
Add local discovery of root-level INSTRUCTIONS.md via discoverCanonicalInstructions() in rule-discovery.ts, and remote discovery via a new pattern in find-discovery.ts. Only the package root is scanned (no subdirectory scanning). Wire instructions into the find command display output and update RemoteContextSummary.
…d, and CLI - planRuleWrites() handles type: 'instruction' via transpileInstructionForAllAgents - addInstructions() follows same pattern as addRules/addPrompts/addAgents - CONTEXT_CONFIGS extended with instruction entry for zero-flag discovery - --instruction/-i flag added to CLI, 'instruction' added to VALID_CONTEXT_TYPES - VALID_TYPES in dotai-lock.ts includes 'instruction' - check and rule-check updated for instruction entries - 32 new tests: e2e-instruction (18) + instruction-pipeline (14) - README.md updated with instruction support across all sections
… behavior Add instruction content type support to the list and remove commands, and ensure instruction target files are never gitignored since they (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md) should always be committed and visible to the team. - list: show instruction entries with filtering, empty states, and global-scope notes - remove: include 'instruction' in type guards and function signatures - rule-add: remove gitignore flag and addToGitignore call for instructions - docs: add 'instruction' to --type flag descriptions in CLI reference and AGENTS.md project description - tests: add 16 tests for instruction list/remove/gitignore behavior
Verify checkRuleUpdates and updateRules handle instruction entries: - detect unchanged instruction content (no false positives) - detect changed upstream instruction content - report error when instruction is removed from source - check instructions alongside rules in the same source - update instruction files with append markers on content change - update lock file hash after instruction update - preserve installedAt timestamp on instruction update
Remove all rule-specific code as a breaking change (Phase 2). This includes deleting rule modules (parser, transpilers, reverse-transpiler, import), removing 'rule' from the ContextType union, cleaning up target agent configs, and stripping rule branches from the install pipeline, discovery, check/update, CLI commands, and all test files. Renamed shared modules from rule-prefixed to context-prefixed names (rule-add → context-add, rule-installer → context-installer, rule-discovery → context-discovery, rule-check → context-check). Legacy rule entries in .dotai-lock.json are silently filtered out during lock file read so existing lock files remain valid. BREAKING CHANGE: The 'rule' content type, --rule/-r flag, --append flag, and 'import' command are removed.
Remove rule-related CLI flags, commands, documentation, and examples. Add deprecation errors for --rule, --append, import command, and init rule that direct users to use instructions instead. - Add clear error messages when users pass --rule, --append, or use dotai import / dotai init rule - Remove --append from help text (instructions always use append mode) - Update README, cli-reference, coding-agent-docs, supported-targets to remove all rule references and document instructions as primary - Delete examples/rule/ and examples/rule-with-overrides/ - Create examples/instruction/ with sample INSTRUCTIONS.md - Clean up stale rule references in JSDoc comments and code comments - Add tests for all deprecation error messages Closes #25
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
PRD #17: feat: replace rules with instructions content type
Closes #17
Closes #19
Closes #20
Closes #21
Closes #22
Closes #23
Closes #24
Closes #25
Completed Sub-Issues
Stuck Sub-Issues
Changes
Features
Tests