docs: Update AI.md to use docs/ subdirectories

[adslaton]

This pull request updates the AI.md file to standardize the documentation paths used by AI assistants.

Changes:

• The File Structure and Cross-References sections in AI.md have been updated to point to the following directories for storing documentation:
  • docs/roadmaps/
  • docs/plans/
  • docs/specs/
  • docs/research/
• This ensures that when AI assistants are instructed to create roadmaps, plans, specs, or research documents, they will create them in a consistent and organized location within the user's project.
• Direct references to CLAUDE.md and GEMINI.md have been removed from the shared AI.md to make the instructions more general.

This change addresses the need to guide AI assistants on where to create files when the idk package is used, without creating those directories in the source repository itself.

[github-actions]

🔒 Security Scan Results

✅ npm audit - Dependency Security

No vulnerable dependencies found.

⚠️ audit-ci Security Check

No results file generated.

⚠️ ESLint Security Analysis

No results file generated.

---

✅ All security scans passed! No issues found.

[github-actions]

🤖 AI Review

Of course. Here is a review of the pull request based on your provided information.

---

Pull Request Review

Repo: user/repo
PR Title: Update AI.md to standardize documentation paths
Branch: feature/standardize-ai-paths

---

Summary of Changes

This pull request modifies the central AI instruction file, AI.md, to standardize the file paths for documentation generated by AI assistants. It replaces a specific roadmap file (docs/roadmaps/ROADMAP.md) with a directory-based approach and introduces new standard directories for plans, specifications, and research (docs/plans/, docs/specs/, docs/research/).

Additionally, it removes explicit, hardcoded references to model-specific files like CLAUDE.md and GEMINI.md to make the core instructions more generic and scalable.

---

Strengths of the Implementation

1. Standardization: The core goal of creating a consistent directory structure is excellent. This promotes project organization and makes it easier for both humans and AI to locate documents. It reduces the chance of AI a-ssistants creating files in arbitrary locations.

2. Scalability: Removing the direct references to CLAUDE.md and GEMINI.md is a great change. It decouples the shared instructions from the specific AI models, making it easier to add or remove support for new models in the future without needing to update this central file.

3. Clarity of Intent: The PR description clearly explains the "why" behind the changes—specifically, that these directories are intended for the user's project context, not the source repository. This context is crucial for understanding the design decision.

---

Issues or Concerns

1. Potential Bug / Ambiguity for AI: The change from a specific file (docs/roadmaps/ROADMAP.md) to a directory (docs/roadmaps/) introduces ambiguity. While the intent is for the AI to create a file inside that directory, the instruction docs/roadmaps/ - Development priorities and future plans doesn't specify a filename. An AI might:

   • Correctly infer it needs to create a file like new-roadmap.md inside the directory.
   • Incorrectly try to write the content to the directory itself, resulting in an error.
   • Ask the user for a filename, which adds friction.
   • Hallucinate a poor or inconsistent filename.

2. Documentation (Broken Links): The links in the Cross-References section ([docs/roadmaps/](docs/roadmaps/)) will likely be broken when viewed on a Git platform (like GitHub or GitLab) if the directories do not exist in the repository. While the PR description clarifies this is by design, it can be a minor point of confusion for human developers browsing the source code. This is a small trade-off, but worth noting.

---

Suggestions for Improvement

To address the ambiguity concern, I recommend making the instructions slightly more explicit. This will guide the AI more effectively without being overly rigid.

Suggestion: Add example filenames in the descriptions to hint at the expected behavior.

Update the File Structure and Cross-References sections as follows:

--- a/AI.md
+++ b/AI.md
@@ -53,10 +53,10 @@
 
 * `information-dense-keywords.md` - The core dictionary content
 * `README.md` - Project documentation and usage guide
-* `docs/roadmaps/ROADMAP.md` - Development priorities and future plans
+* `docs/roadmaps/` - Directory for roadmap documents (e.g., `q4-roadmap.md`)
+* `docs/plans/` - Directory for planning documents (e.g., `new-feature-plan.md`)
+* `docs/specs/` - Directory for specifications (e.g., `api-spec-v2.md`)
+* `docs/research/` - Directory for research notes (e.g., `competitor-analysis.md`)
 * `examples/` - Usage examples and guides
 * `adrs/` - Architecture decision records
 * `AI.md` - This shared AI instruction file
@@ -65,10 +65,10 @@
 
 * [information-dense-keywords.md](information-dense-keywords.md) - The core command dictionary
 * [README.md](README.md) - Main project documentation
-* [docs/roadmaps/ROADMAP.md](docs/roadmaps/ROADMAP.md) - Development roadmap and priorities
+* [docs/roadmaps/](docs/roadmaps/) - Directory for roadmap documents
+* [docs/plans/](docs/plans/) - Directory for planning documents
+* [docs/specs/](docs/specs/) - Directory for specifications
+* [docs/research/](docs/research/) - Directory for research notes
 * [examples/ai-usage-guide.md](examples/ai-usage-guide.md) - AI usage examples
 

This small change provides a clear hint to the AI about its task: "Create a new file with a descriptive name inside this directory."

---

Review Checklist

• Code quality and best practices: N/A (Documentation file). The change follows good principles for project structure.
• Potential bugs or issues: Yes, potential ambiguity for the AI when given a directory instead of a file. (Addressed in Suggestions).
• Security concerns: No. This change does not introduce any security vulnerabilities.
• Performance implications: No. This is a documentation change.
• Test coverage: N/A.
• Documentation updates needed: The PR is a documentation update. No other changes seem necessary, but it would be prudent to ensure the model-specific files (CLAUDE.md, etc.) do not contain conflicting instructions.

---

Overall Recommendation

Request Changes

This is a valuable improvement that enhances the project's structure and scalability for AI collaboration. The proposed changes are minor but will significantly improve the clarity of the instructions for the AI assistant, reducing the risk of errors or ambiguous behavior.

Once the suggested improvements for clarity are incorporated, I would be happy to approve this PR.

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[github-actions]

🔒 Security Review Report

This report contains the results of automated security scans.

✅ No security issues found by Bandit

✅ No vulnerable dependencies found by Safety

No Semgrep results found.

✅ No vulnerabilities found by npm audit

---

Report generated automatically by security review workflow

[github-actions]

🤖 AI Review

Of course. Here is a detailed review of the pull request.

---

Pull Request Review

PR Title: Update AI.md to standardize documentation paths

Overall Recommendation: Approve with Suggestions

This is a well-intentioned and mostly well-executed pull request that improves the structure and guidance for AI assistants. The changes are logical and contribute to better organization. There are a few minor areas for improvement, primarily around developer experience and test code clarity.

---

1. Summary of Changes

This pull request refactors the project's documentation to guide AI assistants into creating new documents (roadmaps, plans, specs, etc.) within standardized directories (docs/roadmaps/, docs/plans/, etc.) rather than pointing to a single, static ROADMAP.md file.

To support this change:

• AI.md, README.md, CONTRIBUTING.md, CLAUDE.md, and GEMINI.md have been updated to link to these new directories.
• The shared AI.md has been generalized by removing links to model-specific files (CLAUDE.md, GEMINI.md).
• The test suite has been updated to ignore links to the docs/ directories, as these directories are not expected to exist in the source repository.

2. Strengths of the Implementation

• Clear Intent: The goal of standardizing file creation paths for AI assistants is excellent. It promotes consistency and organization in projects that use this framework.
• Good Generalization: Removing model-specific links (CLAUDE.md, GEMINI.md) from the shared AI.md is a great application of the DRY (Don't Repeat Yourself) principle. It makes the core instructions more robust and easier to maintain.
• Test-Aware Development: It's a strong positive that you updated the tests to accommodate these changes. Modifying the link validators to prevent CI failures from these "intentionally broken" links shows foresight and a good understanding of the development workflow.

3. Issues and Concerns

Potential Bugs or Issues

• Confusing Logic in link-validation.test.js:
  In tests/link-validation.test.js, the logic for checking existing paths was changed to:

  const isDirectory = fs.existsSync(resolvedPath) && fs.lstatSync(resolvedPath).isDirectory();
  
  if (!fs.existsSync(resolvedPath) && !isDirectory) {
    throw new Error(`Broken relative link: ${link.path} (line ${link.lineNumber})`);
  }

  This if statement is slightly redundant and confusing. fs.existsSync() returns true for both files and directories. If a path does not exist, fs.existsSync(resolvedPath) will be false, and isDirectory will also be false. The condition simplifies to if (true && true), which works but is unnecessarily complex. A simple if (!fs.existsSync(resolvedPath)) would have the same effect and be easier to read.

• Developer Experience with Broken Links:
  While the CI tests will pass, a human developer cloning the repository will encounter broken links when navigating the documentation locally or on GitHub's web UI (e.g., clicking the "Roadmap" link in the README.md). This can be confusing if not explicitly explained.

Security Concerns

• None. The changes are confined to documentation and development-time tests, with no impact on runtime logic, dependencies, or user input handling.

Performance Implications

• None. The changes to the test files are minor and will have a negligible impact on test execution time.

4. Test Coverage

• The test coverage has been correctly adapted. By adding || linkPath.startsWith('docs/') to the exclusion rules in the validators, you've ensured that the new directory links don't cause false negatives in the test suite.
• The simplification of the cross-reference testing in link-validation.test.js is reasonable. The previous complex logic was likely over-engineered, and the new, simpler file existence check is more maintainable.

5. Documentation Updates Needed

The pull request is a documentation update, but it introduces a new convention that should be documented for human contributors.

• Clarify Placeholder Directories: It would be highly beneficial to add a note in CONTRIBUTING.md or the README.md explaining that the docs/* directory links are placeholders for AI-generated content and are not expected to exist in the source repository.

6. Suggestions for Improvement

1. Clarify the purpose of docs/ links:
   In CONTRIBUTING.md or README.md, add a small note to manage expectations for human developers.

   Example for README.md:

   ## 📚 Further Reading
   - [AI Usage Guide](examples/ai-usage-guide.md) - Detailed implementation guidance
   - [Command Definitions](information-dense-keywords.md) - Complete command index
   - [Architecture Decision Records](adrs/) - Design decisions and evolution
   - [Roadmap](docs/roadmaps/) - Future development plans
   
   *Note: Links to `docs/roadmaps/`, `docs/plans/`, etc., are conventions for AI assistants. These directories do not exist in the source repository but should be created in your local project clone.*

2. Simplify the Test Logic:
   Refactor the check in tests/link-validation.test.js for better readability.

   Current Code:

   const isDirectory = fs.existsSync(resolvedPath) && fs.lstatSync(resolvedPath).isDirectory();
   
   if (!fs.existsSync(resolvedPath) && !isDirectory) {
       throw new Error(`Broken relative link: ${link.path} (line ${link.lineNumber})`);
   }

   Suggested Refactor:

   // The link resolution test should not apply to conceptual directories or external URLs.
   if (link.path.startsWith('http') || link.path.startsWith('docs/')) {
     return; // Skip validation for these paths
   }
   
   const resolvedPath = path.resolve(path.dirname(filePath), link.path);
   
   // fs.existsSync works for both files and directories.
   if (!fs.existsSync(resolvedPath)) {
     throw new Error(`Broken relative link: target does not exist at ${link.path} (line ${link.lineNumber})`);
   }

   Note: The check for http and docs should happen before resolving the path. The diff shows the docs/ exclusion was added in one test but not the other; it should be consistently applied. The suggested refactor consolidates this logic.

---

Overall, this is a solid contribution. I recommend implementing the suggestions above to improve clarity and developer experience before merging.

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[adslaton]

I have addressed the feedback and fixed the test suite failures.

Changes:

• Updated , , , , and to use conceptual subdirectories.
• Removed direct references to and from .
• Modified and to ignore links to the conceptual directories, allowing the test suite to pass.

All tests are now passing. The pull request is ready for review.

[adslaton]

I've addressed the AI review feedback.

• The instructions in now include example filenames to guide AI assistants.
• A note has been added to to clarify that the links are conceptual placeholders.
• The test logic in has been simplified for better readability.

All changes have been implemented and the tests are passing.

[github-actions]

🤖 AI Review

Of course. Here is a detailed review of the provided pull request.

---

Pull Request Review

PR Title: Update AI.md to standardize documentation paths

Summary of Changes:
This pull request standardizes the file paths for AI-generated documentation by updating links in AI.md and other relevant files to point to conceptual directories (docs/roadmaps/, docs/plans/, etc.) instead of specific files. To prevent CI failures from these intentionally "broken" links, the link validation tests have been updated to ignore paths starting with docs/. The changes also include generalizing AI.md by removing direct links to model-specific files like CLAUDE.md and GEMINI.md.

---

1. Code Quality and Best Practices

Strengths

• Consistency: The change consistently applies the new directory-based documentation standard across all relevant markdown files (AI.md, README.md, CONTRIBUTING.md, etc.).
• Generalization: Removing model-specific links (CLAUDE.md, GEMINI.md) from the shared AI.md file is an excellent move. It decouples the core instructions from specific implementations, making the system more modular and easier to extend with new AI assistants in the future.
• Test-Driven Change: The author correctly identified that the documentation changes would break the build and proactively updated the tests to accommodate the new conventions. This shows a good understanding of the entire development lifecycle.
• Improved Error Messages: The error message in tests/link-validation.test.js was improved from Broken relative link: ... to Broken relative link: target does not exist at ..., which is slightly more informative.

Suggestions

• Code Duplication in Tests: The logic to skip docs/ paths is duplicated in tests/dictionary-validator.test.js and tests/link-validation.test.js.

  // In dictionary-validator.test.js
  if (linkPath.startsWith('http://') || linkPath.startsWith('https://') || linkPath.startsWith('docs/')) { ... }
  
  // In link-validation.test.js
  if (link.path.startsWith('http') || link.path.startsWith('docs/')) { ... }

  This could be refactored into a shared utility function to keep the logic in one place (Don't Repeat Yourself - DRY). For example, a helper function could be created:

  // in a new tests/test-utils.js or similar
  function isIgnoredLink(linkPath) {
    const ignoredPrefixes = ['http://', 'https://', 'docs/'];
    return ignoredPrefixes.some(prefix => linkPath.startsWith(prefix));
  }

• Magic Strings: The string 'docs/' is now a special, "magic" value in the tests. It would be best practice to add a comment explaining why these paths are being skipped. This will help future developers understand the intent.

  // Suggestion for tests/link-validation.test.js
  // Skip validation for external links and conceptual doc paths intended for AI generation.
  if (link.path.startsWith('http') || link.path.startsWith('docs/')) {
      return;
  }

---

2. Potential Bugs or Issues

I see no major bugs introduced by this change. The primary risk—broken link validation—has been correctly addressed.

One minor concern is the simplification of the testCrossReferences method in tests/link-validation.test.js. The previous implementation had specific logic for validating command definitions within the dictionary/ directory. The new implementation is much simpler and just checks for file/directory existence for all links. While this simplification is cleaner, it's worth double-checking that no specific, valuable validation was lost in the refactoring. Given the context, the new, simpler check seems sufficient.

---

3. Security Concerns

There are no security concerns in this pull request. The changes are limited to documentation files and test scripts that validate local file paths.

---

4. Performance Implications

There are no performance implications. The changes to the test scripts add a negligible string comparison operation, which will not impact test execution time in any meaningful way.

---

5. Test Coverage

The test coverage is being intentionally and correctly modified. The PR adapts the tests to ignore links that are expected to be broken in the source repository. This is not a reduction in useful coverage but rather an alignment of the tests with the project's new conventions. The tests will still correctly catch unintentionally broken links that do not match the ignored patterns.

---

6. Documentation Updates Needed

The documentation has been updated well.

• The core change is in AI.md and is the central purpose of the PR.
• The README.md was thoughtfully updated with a note explaining the convention for other developers. This is a crucial and well-executed part of the change.

Suggestion

In CONTRIBUTING.md, the line [CLAUDE.md](...) and [GEMINI.md](...) contain model-specific guidance was removed entirely. It might be better to rephrase it to guide future contributors who might want to add a new AI model.

Current:

- `AI.md` contains shared instructions for all AI assistants
- Update this file when dictionary changes affect AI behavior

Suggested Improvement:

- `AI.md` contains shared instructions for all AI assistants.
- Model-specific files (e.g., `CLAUDE.md`, `GEMINI.md`) contain platform-specific guidance.
- Update these files when dictionary changes affect AI behavior.

This retains the knowledge of the pattern without explicitly listing every file.

Overall Recommendation

Approve with suggestions.

This is a high-quality pull request that successfully achieves its stated goal. The changes are logical, well-implemented, and consider the impact on the CI/CD pipeline. The suggestions provided are minor and aimed at improving long-term maintainability and contributor guidance. The author can merge this as-is, but incorporating the suggestions would make it even better.

Summary of Recommendations:

1. HIGHLY RECOMMENDED: Add comments to the tests explaining why docs/ links are skipped.
2. RECOMMENDED: Refactor the link-skipping logic into a shared helper function to avoid duplication.
3. SUGGESTED: Consider rewording the updated section in CONTRIBUTING.md to keep the pattern for model-specific files visible.

---

This review was automatically generated by google/gemini-2.5-pro via OpenRouter. Please consider it as supplementary feedback alongside human review.

[adslaton]

I've addressed the latest round of feedback:

• Test Clarity: Added comments to and to explain why links are skipped.
• Refactoring: The link-skipping logic has been refactored into a shared helper function in to improve maintainability.
• Contribution Guidelines: has been updated to restore the pattern for model-specific files.

All changes have been implemented and the tests are passing.

[github-actions]

🎉 This PR is included in version 1.7.3 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀