AI Islands
中文

flatnotes-tasksmd-github-audit

Security & Sandbox B rating

Based on GitHub as the source of truth, it automatically audits the consistency of Flatnotes knowledge base and Tasks.md dashboard, detects outdated notes, missing links and project drift, and generates executable repair plans.

Open external ZIP download → Version：v1.0.0
OpenClaw Claude Code Cursor Codex

Usage instructions

Core usage

This Skill is an audit tool specifically designed to maintain the consistency of individual/team knowledge management systems. It ensures synchronized information through three-party data cross-validation: using GitHub as the authoritative data source, comparing the status of Flatnotes (knowledge base) and Tasks.md (kanban system). Users only need to runnode scripts/audit.mjs --since-days 30 --writeA complete drift report can be generated.

Audit covers three major dimensions:
1. Kanban board health: Check the swim lane rules of Tasks.md (such as WIP limits, priority distribution), card format specifications, blocking status annotations, etc.
2. Project integrity: Verify whether each active project in Flatnotes has a complete note structure (Overview/Research/Plan/Log)
3. GitHub fact checking: Match open source PR status with Tasks cards to ensure that merged work is recorded and ongoing work is tracked

Significant advantages

  • Zero dependency design: Only use Node.js built-in modules, no npm packages introduce supply chain risks
  • Non-intrusive auditing: The default is read-only mode, no data is modified, and the risk is controllable
  • Structured output: Simultaneously generate Markdown human-readable reports and JSON machine parsing formats
  • Intelligent matching algorithm: Reduce the cost of manual verification through multi-dimensional heuristic matching such as PR URL, number, title substring, etc.
  • environment adaptation: Supports overriding the default path through environment variables to adapt to different deployment scenarios

Potential Disadvantages and Limitations

  • Strong dependence on external tools: Must be pre-installed and certifiedghCLI, otherwise GitHub checks will be skipped
  • Heuristic matching is not perfect: The association between PR and card depends on text similarity, and there may be false positives or false negatives.
  • Single user scenario design:The path is hardcoded as/home/ds/..., multi-user shared environment requires manual configuration
  • No real-time synchronization capability: Only a periodic audit tool, not a real-time hook for continuous integration
  • Repair capabilities are limited: Automatic repair is limited to safe metadata supplement, and structural changes require manual confirmation.

Suitable target group

  • Individual developers or small teams using the Flatnotes + Tasks.md combination to manage projects
  • Engineers pursuing a "GitHub as the source of truth" workflow
  • Maintainers who need regular knowledge base health checks
  • Users who are sensitive to supply chain security and prefer zero-dependency tools

Risks of use

  • file system access: All Markdown files in the user configuration directory need to be read, and sensitive note content will be parsed.
  • GitHub API calls:passghThe CLI initiates a network request, which may trigger outbound traffic auditing in the enterprise environment
  • Report a breach risk: The generated audit report contains metadata such as project structure, PR link, etc., and needs to be desensitized and reviewed before sharing.
  • Path traversal hazards: Although the current version uses constant paths, environment variable injection still needs to be verified by the user.

Safety review

Core usage

flatnotes-tasksmd-github-auditIt is a local audit tool designed for Brandon to systematically check the synchronization degree of personal task management system (Tasks.md + Flatnotes) with the actual status of GitHub repository. The operation method is simple and straightforward:

node skills/flatnotes-tasksmd-github-audit/scripts/audit.mjs --since-days 30 --write

The tool scans three major data sources and generates cross-validation reports:

1. Tasks.md Kanban Check: Verify swim lane structural integrity, WIP restrictions (Doing ≤ 3), card format specifications (Outcome/Steps), label system (proj/prio/eff/type) andFlatnotes:pointer integrity
2. Flatnotes Project Note Audit: Ensure that each active project has a standard note structure (00 Overview, 10 Research, 20 Plan, 90 Log). Hub notes include status summary, link area (repo + Tasks filter) and decision area (ADR link)
3. GitHub truth alignment:passghCLI obtains Open PR and recent Merged PR, and cross-verifies whether PR is mapped to Tasks card or project log

The output is Markdown readable report + JSON structured data, which facilitates subsequent automated processing.

Significant advantages

  • Zero dependency security design: Only use Node.js built-in modules (fs, path, child_process, util), no third-party npm packages, completely eliminating the supply chain attack surface
  • Graceful degradation mechanism:whenghWhen not authenticated, GitHub checks are automatically marked asSKIPPED_GITHUB, the script does not crash and local auditing can still run independently
  • Rule-driven quality gate: Built-in lane rules (such asprio-p2Must be located in Backlog), format specification (Blocked must containUnblock:) and other quantifiable inspection items
  • Two-way link verification: Verify both the Tasks card → Flatnotes pointer, and the backlink integrity of the Flatnotes Hub → ADR note
  • Report/fix detachment: Only reports are generated by default. All destructive operations require explicit authorization, complying with the principle of safe least privilege.

Potential Disadvantages and Limitations

  • GitHub dependency restrictions: Requires local installation and official certificationghCLI, and only supports warehouses accessed through gh; private warehouses require additional configuration permissions
  • Heuristic matching limitations: The association between PR and Tasks card relies on URL matching, number matching or title substring heuristics, and there may be false positives or false negatives.
  • Markdown parsing vulnerability: Relying on regular expressions to parse Tasks.md tables and tags, with limited fault tolerance for non-standard formats
  • Single user scenario design:The path is hardcoded as/home/ds/.config/appdata/, although it can be overridden through environment variables, but migration costs exist
  • No incremental audit mechanism: Every time a full scan is performed, the performance of a large historical warehouse may be degraded.

Suitable for the crowd

  • Developers using Tasks.md + Flatnotes combination for project management
  • Technical team leader pursuing bi-directional traceability of GitHub PRs and local tasks
  • Individual contributors who need regular "Kanban cleaning" but manual inspection is time-consuming
  • Privacy-sensitive users who prefer local priority and data autonomy

General risks

  • File system read range: Requires authorization to access the local notes directory. Although it is read-only, you still need to confirm that the path configuration is correct.
  • gh CLI certification status: If an uncertified gh instance is used, GitHub verification will be skipped, which may lead to "false negatives" (actually drifted but not detected)
  • Report interpretation threshold: The output contains a large number of fine-grained checks, which require an understanding of Tasks.md swim lane semantics and Flatnotes project structure to take effective action.
productivityproject-program-managementautomationdocsgitbackenddevops

Copyright and takedown notice: AI Islands curates this page from public information. Skills, code, documents and packages remain the property of their original authors or rights holders. This listing is provided for indexing, research and installation convenience. If you believe any listing or download link infringes your rights, contact ai-islands@streamflowintel.com with proof of ownership, relevant URLs and your request. We will review and remove or adjust the content promptly. Review package permissions, dependencies and safety risks before installing.

Related Agent Skills