# PMake

**Repository Path**: suyuexinghen28/pmake

## Basic Information

- **Project Name**: PMake
- **Description**: PMake is a meta-build system that translates high-level project manifests into executable automation for agent assistants. 
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-29
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PMake

PMake is a meta-build system that translates high-level project manifests into executable automation for agent assistants. By parsing a `PMakeLists.txt` manifest, PMake emits a ready-to-run GNU Make environment that coordinates agent prompts, captures worklogs, and manages retry loops through error headers.

## Features
- **Manifest-driven builds** – describe proposals, roadmaps, and tasks in a declarative `PMakeLists.txt`.
- **Essential vs optional targets** – enforce critical work while keeping stretch tasks isolated.
- **Automatic logging** – persist worklogs and error trails with state tracking and retry metadata.
- **Skill/library integration** – reference shared prompts or external projects via `skill://` and `extern://` URIs.
- **Rich introspection** – use `make info` to inspect implementation status, dependencies, and log locations for every target.

## Getting Started

### Prerequisites
- Python 3.9 or later
- GNU Make (any POSIX-compatible implementation)

> PMake is currently packaged as a Python module within this repository. You can run it directly via `python -m pmake` without installation.

### Quick Start
```bash
# 1. Author or edit your project manifest
$ vim PMakeLists.txt

# 2. Generate build artifacts
$ python -m pmake configure

# 3. Run essential agents
$ make -C .pmake

# 4. Optional: run stretch targets
$ make -C .pmake optional

# 5. Inspect status and worklogs at any time
$ make -C .pmake info
```

Running `python -m pmake configure` creates a `.pmake/` directory containing the generated `Makefile`, metadata, include fragments, and state files. Worklogs and error logs are written under the `logs/` directory specified in the manifest.

## Writing `PMakeLists.txt`

Every manifest is divided into sections:

```ini
[project]
name = ExampleProject
version = 0.1.0
store_dir = logs/example
globals = docs/principles.md, docs/env.md

[targets]
# name : kind : deps : executor : output
bootstrap         : essential :  : agent : bootstrap/worklog.md
analysis          : essential : bootstrap : agent : analysis/worklog.md
comparison-report : optional  : analysis,skill://document-skills : agent : reports/comparison.md

[extern]
shared-math = ../shared/mathlib

[proposal]
- Capture the project vision here.
- Use bullet points or paragraphs.

[roadmap]
- Phase 1: Setup tooling
- Phase 2: Build core features
- Phase 3: Evaluate optional enhancements
```

### Section Reference
- **[project]** – project metadata. If `store_dir` is omitted it defaults to `logs/<name>`. `globals` accepts a comma-separated list of files that will be passed to agents as context.
- **[targets]** – define work units. Each line has five fields separated by ` : ` (spaces around colon are required):
  1. `name` – unique target identifier.
  2. `kind` – `essential` or `optional`.
  3. `deps` – comma-separated names of other targets, `skill://` URIs, or `extern://` references. Optional targets cannot be dependencies of other targets.
  4. `executor` – how the runtime should invoke the task (default `agent`).
  5. `output` – relative worklog path; the error log is the same name with `.err` appended.
- **[extern]** – optional mapping of aliases to external project roots.
- **[proposal]** & **[roadmap]** – freeform narrative sections preserved for context.

## Command Reference

| Command | Purpose |
|---------|---------|
| `python -m pmake configure [--manifest PATH]` | Parse the manifest and regenerate `.pmake/` artifacts. |
| `python -m pmake disable TARGET [TARGET ...]` | Disable optional targets (updates `.pmake/state/disabled.json`). |
| `python -m pmake skills-list [--skills-dir PATH]` | List available skill templates (defaults to `/home/linden/claude/zclaude/skills`). |
| `python -m pmake info [--manifest PATH]` | Print the status of each target, including dependencies and log locations. |

Generated Makefile targets include:
- `make -C .pmake` / `make all` – run all essential targets.
- `make -C .pmake optional` – run optional targets.
- `make -C .pmake info` – delegate to `pmake info` for a textual report.
- `make -C .pmake clean` – remove `.ok`/`.fail` state stamps.
- `make -C .pmake disable-<target>` – convenience wrapper for disabling optional targets.

## Logs and Error Recovery
- Successful runs append to the target’s worklog with a timestamped header inside the configured store directory.
- Failures append to `<output>.err`, update `.pmake/include/.err/<target>.mk`, and mark `.pmake/state/<target>.fail`.
- When a target succeeds after failing, the runtime archives the most recent error log under `archive/` and removes the error include so subsequent runs have a clean slate.
- Essential targets propagate non-zero exit codes on failure; optional targets record failure state but allow the overall `make optional` command to continue.

## Repository Layout

```
pmake/                 # Python package (CLI, parser, generator, runtime)
PMakeLists.txt         # Example manifest
docs/                  # Design notes and user manuals
logs/                  # Generated worklogs (after running make)
.pmake/                # Generated build artifacts (after configure)
```

## Contributing
1. Run `python -m compileall pmake` before submitting changes to ensure syntax validity.
2. Update or add tests/docs when changing manifest parsing, generator layouts, or runtime behavior.
3. File issues or proposals using the `PMakeLists.txt` `[proposal]` section or open a discussion in `docs/`.

## Further Reading
- `docs/pmake-design.md` – high-level system design.
- `AGENTS.md` – guidelines for agent operators responding to PMake targets.
- `docs/user-manual.md` – detailed walkthroughs and troubleshooting tips.