{"id":50303687,"url":"https://github.com/rrbarrero/postcraft","last_synced_at":"2026-05-28T14:30:31.443Z","repository":{"id":357813865,"uuid":"1238632571","full_name":"rrbarrero/postcraft","owner":"rrbarrero","description":"PostCraft is a local editorial pipeline for turning software repositories into credible technical portfolio posts.","archived":false,"fork":false,"pushed_at":"2026-05-14T11:09:38.000Z","size":415,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T12:32:52.663Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rrbarrero.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-05-14T09:53:58.000Z","updated_at":"2026-05-14T11:09:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/rrbarrero/postcraft","commit_stats":null,"previous_names":["rrbarrero/postcraft"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/rrbarrero/postcraft","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Fpostcraft","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Fpostcraft/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Fpostcraft/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Fpostcraft/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rrbarrero","download_url":"https://codeload.github.com/rrbarrero/postcraft/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rrbarrero%2Fpostcraft/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33613431,"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-05-28T02:00:06.440Z","response_time":99,"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":[],"created_at":"2026-05-28T14:30:27.814Z","updated_at":"2026-05-28T14:30:31.434Z","avatar_url":"https://github.com/rrbarrero.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PostCraft\n\nPostCraft is a local editorial pipeline for turning software repositories into\ncredible technical portfolio posts.\n\n![alt text](image.png)\n\nThe project solves a common gap in engineering portfolios: real projects often\ncontain useful design decisions, trade-offs, tests, automation, and learning, but\nthat evidence usually stays buried in the repository. PostCraft is meant to\nread a local codebase, understand what it actually contains, and transform that\nevidence into a technical article that explains the problem, the design, the\nengineering judgement, and the professional value of the work.\n\nThe system is designed around evidence before narrative. It first scans the\nrepository, identifies the stack, entrypoints, documentation, tests,\nconfiguration, automation, and relevant source files, and selects a small set of\nfiles that can support a grounded analysis. From there, a multi-agent workflow\nbuilds a factual inventory, interprets the architecture and main flows, proposes\nportfolio-oriented angles, extracts professional signals, drafts the post,\nreviews technical claims, improves the tone, prepares metadata, and finally\ncreates a blog draft.\n\nThe goal is not to generate generic marketing copy or inflate a project beyond\nwhat the code supports. The goal is to produce articles that show engineering\njudgement: why a project exists, what constraints shaped it, which technical\ndecisions mattered, what trade-offs were accepted, how maintainability and\ntesting were approached, what was learned, and what could reasonably come next.\n\nPostCraft should keep the process auditable. Each run should produce a local\nworkspace with the files and intermediate artifacts used to create the post:\ninventory, selected evidence, project facts, technical analysis, candidate\nangles, portfolio positioning, outline, draft, technical review, final article,\nmetadata, warnings, and publication result. This makes it possible to review how\nthe post was generated and to correct unsupported claims before anything reaches\nthe blog.\n\nPublishing is part of the complete workflow, but it must remain controlled. The\nsystem should create drafts through the blog MCP and mark them as drafts by\ndefault. Final publication stays a manual editorial decision, with the generated\npost traceable back to repository evidence and review artifacts.\n\n## Project Evolution\n\nThis section documents what has already been implemented in PostCraft and will\nbe updated as the pipeline grows.\n\nOngoing progress notes are tracked in [progress/20260514.md](progress/20260514.md).\nThis is where we will keep updating the concrete evolution of the project,\nincluding what changed, what the latest runs revealed, and what needs to be\nfixed next.\n\n### Implemented Flow\n\nPostCraft currently supports a local, auditable draft-generation flow. The user\npasses a repository path to the CLI, and the system creates a workspace with the\nintermediate evidence and writing artifacts produced during the run.\n\nThe implemented flow is:\n\n```text\nlocal repository\n  -\u003e project scanner\n  -\u003e repository analyst\n  -\u003e architecture narrator\n  -\u003e portfolio positioning\n  -\u003e outline generator\n  -\u003e technical writer\n  -\u003e technical reviewer\n  -\u003e final editor or blocked finalization\n  -\u003e local workspace\n```\n\nThe main command is:\n\n```bash\nmake draft PATH=/path/to/repository\n```\n\nInternally, this calls:\n\n```bash\nuv run python -m src.adapters.primary.cli draft-project-post /path/to/repository\n```\n\nThere is also an analysis-oriented command:\n\n```bash\nmake analyze PATH=/path/to/repository\n```\n\n### Implemented Agents\n\n#### Project Scanner Agent\n\nThe `ProjectScannerAgent` is the factual entry point of the pipeline. It scans a\nlocal project directory and builds the base evidence used by the rest of the\nsystem.\n\nIt currently detects:\n\n- files and directories in the repository;\n- language counts by file extension;\n- known project manifests such as `pyproject.toml`, `Cargo.toml`, and similar\n  configuration files;\n- probable technologies;\n- relevant project signals such as entrypoints, documentation, tests,\n  automation, and architecture-related folder names;\n- a bounded list of selected files that are likely to help explain the project.\n\nThe scanner is intentionally evidence-first. Its job is not to write narrative,\nbut to decide what the system knows about the repository and which files deserve\nattention in later stages.\n\n#### Repository Analyst Agent\n\nThe `RepositoryAnalystAgent` takes the scanner output and asks the LLM for a\ntechnical interpretation of the repository.\n\nIt uses the selected evidence files and observed project signals to produce:\n\n- an architecture-oriented analysis;\n- observed or tentative patterns;\n- a technical summary;\n- strengths and limitations;\n- doubts where the available evidence is incomplete.\n\nThis agent is where the system starts moving from raw inventory to technical\nunderstanding, but it is still expected to separate observed facts from\nreasonable inferences.\n\n#### Architecture Narrator Agent\n\nThe `ArchitectureNarratorAgent` turns the technical analysis into possible\narticle angles.\n\nIt proposes several portfolio-oriented narratives, each with:\n\n- a thesis;\n- evidence;\n- portfolio value;\n- risks;\n- a recommended angle;\n- claims that should be avoided.\n\nIts purpose is to prevent the post from becoming a simple technology inventory.\nInstead of saying only what stack the project uses, this step tries to identify\nwhat story the project can credibly tell.\n\n#### Portfolio Positioning Agent\n\nThe `PortfolioPositioningAgent` translates technical evidence into professional\nsignals.\n\nIt identifies:\n\n- strong signals that are well supported by the repository;\n- moderate signals that can be used carefully;\n- claims that should not be made;\n- phrases that fit the post;\n- phrases that should be avoided because they sound inflated or unsupported.\n\nThis agent is responsible for keeping the article useful as portfolio material\nwithout turning it into CV-style self-promotion.\n\n#### Outline Agent\n\nThe `OutlineAgent` creates the structure of the article before the first draft\nis written.\n\nIt organizes the post around a story such as:\n\n```text\nproblem -\u003e project goal -\u003e design -\u003e decisions -\u003e trade-offs -\u003e learning\n```\n\nThe outline includes the intended purpose of each section and the evidence that\nshould be used there. This gives the writer a plan and makes the article less\nlikely to collapse into a list of dependencies.\n\n#### Technical Writer Agent\n\nThe `TechnicalWriterAgent` writes the first Markdown draft from the outline,\ntechnical analysis, and portfolio positioning.\n\nIts role is to produce a readable technical article using only supported claims.\nIt is instructed to avoid unsupported production claims, avoid overstating the\narchitecture, and mark uncertain claims as pending verification when needed.\n\n#### Technical Reviewer Agent\n\nThe `TechnicalReviewerAgent` reviews the draft against the project facts and\ntechnical analysis.\n\nIt classifies the content into:\n\n- supported claims;\n- weak or unsupported claims;\n- exaggerations;\n- required corrections;\n- optional improvements;\n- final verdict.\n\nThe reviewer can return `PASS` or `BLOCK`. If it returns `BLOCK`, the pipeline\ndoes not pretend that the draft is final.\n\n#### Final Editor Agent\n\nThe `FinalEditorAgent` is used only when the technical review allows\nfinalization.\n\nIt applies the review feedback, softens unsupported wording, removes weak\nclaims, and produces the final local Markdown post.\n\nIf the review blocks finalization, PostCraft writes a blocked `final.md`\nartifact explaining that the draft needs correction before it can be treated as\nfinal.\n\n### Workspace Artifacts\n\nEach draft run creates a timestamped workspace under `workspaces/`.\n\nThe currently generated artifacts are:\n\n```text\ninput.json\nfile_inventory.md\nselected_files.md\nproject_facts.md\ntechnical_analysis.md\npost_angles.md\nportfolio_positioning.md\noutline.md\ndraft.md\ntechnical_review.md\nfinal.md\nwarnings.md\n```\n\nThe workspace is meant to make the generation process inspectable. A user can\nopen the inventory, see which files were selected as evidence, inspect the\nanalysis, review the chosen angle, read the draft, and understand why the final\npost was produced or blocked.\n\n### Metrics\n\nEach run also writes a metrics snapshot to:\n\n```text\nlogs/last_run_metrics.json\n```\n\nThe metrics include:\n\n- command name;\n- project path;\n- request options such as audience, language, and target length;\n- selected file count and selected paths;\n- selected excerpt size;\n- artifact character counts;\n- pipeline timings;\n- warning count;\n- whether the technical review blocked finalization.\n\nThese metrics are useful for understanding how a generation behaved and for\ndebugging why a specific run produced a weak or blocked draft.\n\n### Current Boundary\n\nThe implemented system is still local-first. It can analyze repositories and\ngenerate auditable draft workspaces, but it does not yet publish posts to the\nblog.\n\nThe intended publishing behavior remains: when publication support is added,\nPostCraft should create blog entries as drafts through the blog MCP, keep\n`draft: true`, and leave final publication as a manual editorial decision.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbarrero%2Fpostcraft","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frrbarrero%2Fpostcraft","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frrbarrero%2Fpostcraft/lists"}