{"id":51389898,"url":"https://github.com/nikolajflojgaard/code-doc-pipeline","last_synced_at":"2026-07-03T22:35:10.432Z","repository":{"id":366862649,"uuid":"1278200591","full_name":"nikolajflojgaard/code-doc-pipeline","owner":"nikolajflojgaard","description":"AgentSkill for generating maintainable codebase documentation, diagrams, and CI documentation drift checks","archived":false,"fork":false,"pushed_at":"2026-06-25T08:40:03.000Z","size":69,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-03T22:35:03.695Z","etag":null,"topics":["agentskill","ci-cd","code-documentation","documentation","mermaid"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikolajflojgaard.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-23T15:00:59.000Z","updated_at":"2026-06-25T08:40:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nikolajflojgaard/code-doc-pipeline","commit_stats":null,"previous_names":["nikolajflojgaard/code-doc-pipeline"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/nikolajflojgaard/code-doc-pipeline","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolajflojgaard%2Fcode-doc-pipeline","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolajflojgaard%2Fcode-doc-pipeline/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolajflojgaard%2Fcode-doc-pipeline/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolajflojgaard%2Fcode-doc-pipeline/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikolajflojgaard","download_url":"https://codeload.github.com/nikolajflojgaard/code-doc-pipeline/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikolajflojgaard%2Fcode-doc-pipeline/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35104115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-03T02:00:05.635Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentskill","ci-cd","code-documentation","documentation","mermaid"],"created_at":"2026-07-03T22:35:09.817Z","updated_at":"2026-07-03T22:35:10.421Z","avatar_url":"https://github.com/nikolajflojgaard.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Code Doc Pipeline\n\nAn AgentSkill for generating useful documentation from codebases, including architecture docs, API/interface docs, operational notes, Mermaid diagrams, and CI/CD documentation drift checks.\n\nThe point is not to dump a repo tree into Markdown. The point is to keep documentation close enough to the code that it can be regenerated, reviewed, and trusted.\n\n## What It Helps With\n\n- Generate architecture documentation from source code and config\n- Produce Mermaid/C4-style diagrams as a default output, not an afterthought\n- Create sequence, flow, data-flow, context, component, and deployment diagrams where the code supports them\n- Document APIs, events, jobs, modules, deployment surfaces, and config\n- Separate observed facts from inferred behavior\n- Add pipeline checks so documentation drift is visible in pull requests\n- Extract runtime flows from routes into handler/service/repository/data hints\n- Use Python AST-backed route analysis and structured TypeScript/JavaScript symbol resolution\n- Preserve human-written context while refreshing generated sections\n\n## Repository Layout\n\n```text\ncode-doc-pipeline/\n  .github/\n    workflows/\n      validate.yml\n  SKILL.md\n  agents/\n    openai.yaml\n  references/\n    diagram-patterns.md\n    doc-structure.md\n    pipeline-patterns.md\n  scripts/\n    code_docs.py\n    inventory_repo.py\n  examples/\n    tiny-api/\n  tests/\n    test_code_docs.py\n```\n\n## Install\n\nInstall the CLI in editable mode while developing:\n\n```bash\ngit clone https://github.com/nikolajflojgaard/code-doc-pipeline.git\ncd code-doc-pipeline\npython3 -m pip install -e .\n```\n\nThen run:\n\n```bash\ncode-docs generate /path/to/repo\ncode-docs check /path/to/repo\ncode-docs review /path/to/repo\n```\n\nYou can also copy this folder into your Codex/OpenClaw skills directory:\n\n```bash\nmkdir -p ~/.codex/skills\ngit clone https://github.com/nikolajflojgaard/code-doc-pipeline.git ~/.codex/skills/code-doc-pipeline\n```\n\nThen invoke it explicitly:\n\n```text\nUse $code-doc-pipeline to generate pipeline-ready architecture documentation for this repository.\n```\n\n## Quick Start\n\nFrom a repository you want to document:\n\n```bash\ncode-docs generate .\n```\n\nThis creates:\n\n```text\ndocs/\n  README.md\n  architecture.md\n  interfaces.md\n  operations.md\n  diagrams/\n    context.mmd\n    container-or-flow.mmd\n    critical-sequence.mmd\n    data-flow.mmd\n    deployment.mmd\n  generated/\n    code-doc-inventory.json\n```\n\nThen ask the agent to review and improve the generated baseline:\n\n```text\nUse $code-doc-pipeline to create docs/README.md, docs/architecture.md, docs/interfaces.md, docs/operations.md, and Mermaid context, flow, sequence, and data-flow diagrams for this repo. Preserve existing human-written docs where possible.\n```\n\n## CLI\n\n```bash\n# Generate or refresh docs and diagrams\ncode-docs generate .\n\n# CI mode: regenerate and fail if docs changed\ncode-docs check .\n\n# Non-writing summary mode\ncode-docs review .\n\n# Lightweight Mermaid validation\ncode-docs validate-diagrams .\n\n# Inventory only\npython3 scripts/inventory_repo.py . --out docs/generated/code-doc-inventory.json\n```\n\n## Configuration\n\nAdd `code-docs.yml` at the repository root:\n\n```yaml\ndocs_dir: docs\nmax_files: 5000\nservice_name: customer-api\nowner: platform-team\nstrict: true\nrequired_diagrams:\n  - context.mmd\n  - container-or-flow.mmd\n  - critical-sequence.mmd\n  - data-flow.mmd\n  - deployment.mmd\nexclude:\n  - node_modules\n  - dist\n  - generated\n```\n\nThe parser intentionally supports a small YAML subset so the tool stays dependency-free. In strict mode, ownership is required and the configured diagram set is enforced in `check` and `validate-diagrams`.\n\n## CI Example\n\nThe workflow can be strict with `check`, advisory with `review`, or both. For pull requests in the same repository, the example below keeps one sticky docs review comment updated instead of adding a new comment every run.\n\n```yaml\nname: Code documentation\n\non:\n  pull_request:\n  workflow_dispatch:\n\npermissions:\n  contents: read\n  pull-requests: write\n\njobs:\n  docs:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: actions/setup-python@v5\n        with:\n          python-version: \"3.12\"\n      - name: Install code-doc-pipeline\n        run: python3 -m pip install git+https://github.com/nikolajflojgaard/code-doc-pipeline.git\n      - name: Check documentation drift\n        run: code-docs check .\n      - name: Add docs review summary\n        if: always()\n        run: code-docs review . --github-summary --report /tmp/code-doc-review.md\n      - name: Update PR documentation comment\n        if: github.event_name == 'pull_request' \u0026\u0026 github.event.pull_request.head.repo.full_name == github.repository\n        env:\n          GH_TOKEN: ${{ github.token }}\n          PR_NUMBER: ${{ github.event.pull_request.number }}\n          REPO: ${{ github.repository }}\n        run: |\n          marker='\u003c!-- code-doc-pipeline:review --\u003e'\n          body_file=/tmp/code-doc-review-with-marker.md\n          printf '%s\\n\\n' \"$marker\" \u003e \"$body_file\"\n          cat /tmp/code-doc-review.md \u003e\u003e \"$body_file\"\n\n          comment_id=\"$(\n            gh api \"repos/$REPO/issues/$PR_NUMBER/comments\" \\\n              --jq \".[] | select(.user.login == \\\"github-actions[bot]\\\" and (.body | contains(\\\"$marker\\\"))) | .id\" \\\n              | head -n 1\n          )\"\n\n          if [ -n \"$comment_id\" ]; then\n            body=\"$(cat \"$body_file\")\"\n            gh api \"repos/$REPO/issues/comments/$comment_id\" --method PATCH --field body=\"$body\"\n          else\n            gh pr comment \"$PR_NUMBER\" --repo \"$REPO\" --body-file \"$body_file\"\n          fi\n```\n\nIn a mature setup, wrap this in your own `code-docs generate` and `code-docs check` commands so teams do not need to remember skill paths.\n\n## Example\n\nSee [`examples/tiny-api`](examples/tiny-api) for a small Express-style API with generated documentation, Mermaid diagrams, and route-to-service/repository flow detection.\n\n## Documentation Philosophy\n\nGood generated documentation should:\n\n- explain system ownership and boundaries\n- link back to code, config, tests, schemas, and deployment files\n- include Mermaid diagrams that are small enough to review in pull requests\n- show both structure and behavior when the codebase is non-trivial\n- mark uncertainty instead of inventing facts\n- keep generated sections deterministic\n- avoid leaking secrets or private environment values\n\nBad generated documentation:\n\n- rewrites every function into prose\n- creates unreadable mega-diagrams\n- produces noisy diffs on every run\n- hides assumptions\n- becomes a second stale source of truth\n\n## Status\n\nProduction baseline: includes an installable CLI, deterministic generation/check behavior, Python AST-backed flow analysis, structured TypeScript/JavaScript flow resolution, stdlib tests, and GitHub Actions validation. Still designed to be adapted per repo rather than pretending one documentation generator can understand every architecture perfectly.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolajflojgaard%2Fcode-doc-pipeline","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikolajflojgaard%2Fcode-doc-pipeline","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikolajflojgaard%2Fcode-doc-pipeline/lists"}