pcdd 0.4.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pcdd-0.4.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 aledepaoligampel
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
pcdd-0.4.0/PKG-INFO ADDED
@@ -0,0 +1,100 @@
1
+ Metadata-Version: 2.4
2
+ Name: pcdd
3
+ Version: 0.4.0
4
+ Summary: Progressive Change-Driven Development: a local toolkit for working with AI coding agents
5
+ Author: aledepaoligampel
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/aledepaoligampel/pcdd
8
+ Classifier: Environment :: Console
9
+ Classifier: Programming Language :: Python :: 3
10
+ Requires-Python: >=3.9
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Dynamic: license-file
14
+
15
+ # PCDD
16
+
17
+ **Progressive Change-Driven Development**
18
+
19
+ Each change, just enough process.
20
+
21
+ PCDD is a local toolkit for working with AI coding agents. It helps a person and an agent agree on a change, keep enough context to resume it, and verify the result before calling it done.
22
+
23
+ The idea is to add structure as the work needs it. A small, well-understood fix can proceed directly. A substantial change gets approved specifications, tasks, and evidence. A risky change gets independent review and verification before commit approval. Size alone does not determine risk.
24
+
25
+ ## How it works
26
+
27
+ 1. **Understand the request.** The agent reads relevant project context and resolves decisions that affect the work.
28
+ 2. **Define the change.** For substantial work, record verifiable specifications and get approval before implementation.
29
+ 3. **Implement and verify.** Use test-first development when there is a deterministic test and a clear expected result; otherwise record the alternative evidence. Run the project's checks.
30
+ 4. **Keep continuity.** Record tasks, evidence, and the next step in a change document so a new session can pick up the work.
31
+ 5. **Accept the result.** The user tests the outcome before the change is considered complete. Commits and publication follow the project's authorization rules.
32
+
33
+ The starting context stays small: a short core points the agent to relevant instructions and project files. Detailed skills are loaded when needed.
34
+
35
+ ## PCDD, SDD, and ODD
36
+
37
+ These approaches overlap. The comparison below describes their organizing ideas; individual implementations can differ.
38
+
39
+ | Approach | Organizing idea | Practical emphasis |
40
+ | --- | --- | --- |
41
+ | **SDD — Spec-Driven Development** | Use a specification to guide implementation and verification. | Make intended behavior explicit and carry it through planning, code, and checks. |
42
+ | **ODD — Organic Driven Development** | Adapt the workflow to the request and available context. | Handle understood work directly and preserve context for substantial work. |
43
+ | **PCDD — Progressive Change-Driven Development** | Organize work around a change, adding definition and checks as needed. | Use approved specifications for substantial work, independent review for high risk, and local records for continuation and acceptance. |
44
+
45
+ PCDD uses specifications and adapts process to the work. Its concrete choices are a local CLI, Markdown change records, project-owned gates, and agent skills. It does not require an external memory service or a particular application stack. No comparative token, speed, or quality advantage has been established.
46
+
47
+ ## What's included
48
+
49
+ - **Codex, Claude Code, and Antigravity adapters**, installed in the target project.
50
+ - **Four skills:** `pcdd-work`, `pcdd-review`, `pcdd-commit`, and `pcdd-commit-review`.
51
+ - **Installation and maintenance:** preview changes, check an installation, update managed files, and recover or roll back transactions.
52
+ - **Change records:** specifications, task states, verification evidence, and continuation notes.
53
+ - **Progress and time:** task counts and explicitly recorded work intervals, available as human-readable output or JSON.
54
+ - **English and Spanish CLI output.** Agent responses follow the user's language; project documents follow the project's conventions.
55
+
56
+ ## Try it
57
+
58
+ Requires **Python 3.9+**, with no runtime dependencies. PCDD is not published to a package registry yet; install it from the Git repository with [uv](https://docs.astral.sh/uv/) (recommended) or [pipx](https://pipx.pypa.io/). Both put the `pcdd` command on your `PATH` in an isolated environment:
59
+
60
+ ```sh
61
+ uv tool install pcdd --from git+https://github.com/aledepaoligampel/pcdd
62
+ # or
63
+ pipx install git+https://github.com/aledepaoligampel/pcdd
64
+ ```
65
+
66
+ If you don't have uv, install it with `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh` (see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for Windows and other options). For pipx, use `brew install pipx && pipx ensurepath`. Open a new terminal afterwards so `pcdd` is on your `PATH`.
67
+
68
+ You can also install from a local checkout with `uv tool install /path/to/pcdd` or `pipx install /path/to/pcdd`. To upgrade, run `uv tool upgrade pcdd` or `pipx upgrade pcdd`.
69
+
70
+ Then work from the project where you want to use PCDD:
71
+
72
+ ```sh
73
+ cd /path/to/your-project
74
+ pcdd init --dry-run
75
+ pcdd init
76
+ pcdd doctor
77
+ ```
78
+
79
+ `init` installs Codex and Claude Code by default. Select Antigravity with `pcdd init --adapters antigravity`, or combine adapters with commas, such as `--adapters codex,claude,antigravity`. Codex and Antigravity share `AGENTS.md` and the four skills in `.agents/skills/`; Claude Code also uses `CLAUDE.md` and `.claude/skills/`. Review the preview before applying it. Existing installations keep their adapter selection when updated.
80
+
81
+ Without installing, you can run a checkout directly with `python3 /path/to/pcdd/pcdd.py` or add `/path/to/pcdd/bin` to your `PATH`; use `--project /path/to/your-project` before the subcommand to target a project without changing directories.
82
+
83
+ Open a new agent session in the target project and describe the change you want. The installed instructions guide the agent through the appropriate workflow. Configure real project checks before committing; a fresh installation has no gate commands yet.
84
+
85
+ To check the toolkit itself:
86
+
87
+ ```sh
88
+ make ready
89
+ make package-check # builds and installs a wheel in a temporary venv; needs network
90
+ ```
91
+
92
+ See [usage and recovery](USAGE.md), [design](docs/design.md), and the [roadmap](docs/roadmap.md) for details. These project documents are currently in Spanish.
93
+
94
+ PCDD is released under the [MIT License](LICENSE).
95
+
96
+ ## Current scope
97
+
98
+ PCDD v0.4 is an early toolkit. Antigravity installation is covered by CLI tests, with a discovery and continuation pilot in Antigravity CLI. Behavior in the graphical IDE has not been verified; check discovery in the client you use. The CLI manages files and records; the instructions guide agent behavior. It does not technically enforce every workflow rule or guarantee that a model follows it.
99
+
100
+ Task counts measure completed tasks, not effort. Recorded time covers explicitly opened and closed intervals, not necessarily the full development duration. Project checks and human acceptance remain necessary.
pcdd-0.4.0/README.md ADDED
@@ -0,0 +1,86 @@
1
+ # PCDD
2
+
3
+ **Progressive Change-Driven Development**
4
+
5
+ Each change, just enough process.
6
+
7
+ PCDD is a local toolkit for working with AI coding agents. It helps a person and an agent agree on a change, keep enough context to resume it, and verify the result before calling it done.
8
+
9
+ The idea is to add structure as the work needs it. A small, well-understood fix can proceed directly. A substantial change gets approved specifications, tasks, and evidence. A risky change gets independent review and verification before commit approval. Size alone does not determine risk.
10
+
11
+ ## How it works
12
+
13
+ 1. **Understand the request.** The agent reads relevant project context and resolves decisions that affect the work.
14
+ 2. **Define the change.** For substantial work, record verifiable specifications and get approval before implementation.
15
+ 3. **Implement and verify.** Use test-first development when there is a deterministic test and a clear expected result; otherwise record the alternative evidence. Run the project's checks.
16
+ 4. **Keep continuity.** Record tasks, evidence, and the next step in a change document so a new session can pick up the work.
17
+ 5. **Accept the result.** The user tests the outcome before the change is considered complete. Commits and publication follow the project's authorization rules.
18
+
19
+ The starting context stays small: a short core points the agent to relevant instructions and project files. Detailed skills are loaded when needed.
20
+
21
+ ## PCDD, SDD, and ODD
22
+
23
+ These approaches overlap. The comparison below describes their organizing ideas; individual implementations can differ.
24
+
25
+ | Approach | Organizing idea | Practical emphasis |
26
+ | --- | --- | --- |
27
+ | **SDD — Spec-Driven Development** | Use a specification to guide implementation and verification. | Make intended behavior explicit and carry it through planning, code, and checks. |
28
+ | **ODD — Organic Driven Development** | Adapt the workflow to the request and available context. | Handle understood work directly and preserve context for substantial work. |
29
+ | **PCDD — Progressive Change-Driven Development** | Organize work around a change, adding definition and checks as needed. | Use approved specifications for substantial work, independent review for high risk, and local records for continuation and acceptance. |
30
+
31
+ PCDD uses specifications and adapts process to the work. Its concrete choices are a local CLI, Markdown change records, project-owned gates, and agent skills. It does not require an external memory service or a particular application stack. No comparative token, speed, or quality advantage has been established.
32
+
33
+ ## What's included
34
+
35
+ - **Codex, Claude Code, and Antigravity adapters**, installed in the target project.
36
+ - **Four skills:** `pcdd-work`, `pcdd-review`, `pcdd-commit`, and `pcdd-commit-review`.
37
+ - **Installation and maintenance:** preview changes, check an installation, update managed files, and recover or roll back transactions.
38
+ - **Change records:** specifications, task states, verification evidence, and continuation notes.
39
+ - **Progress and time:** task counts and explicitly recorded work intervals, available as human-readable output or JSON.
40
+ - **English and Spanish CLI output.** Agent responses follow the user's language; project documents follow the project's conventions.
41
+
42
+ ## Try it
43
+
44
+ Requires **Python 3.9+**, with no runtime dependencies. PCDD is not published to a package registry yet; install it from the Git repository with [uv](https://docs.astral.sh/uv/) (recommended) or [pipx](https://pipx.pypa.io/). Both put the `pcdd` command on your `PATH` in an isolated environment:
45
+
46
+ ```sh
47
+ uv tool install pcdd --from git+https://github.com/aledepaoligampel/pcdd
48
+ # or
49
+ pipx install git+https://github.com/aledepaoligampel/pcdd
50
+ ```
51
+
52
+ If you don't have uv, install it with `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh` (see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for Windows and other options). For pipx, use `brew install pipx && pipx ensurepath`. Open a new terminal afterwards so `pcdd` is on your `PATH`.
53
+
54
+ You can also install from a local checkout with `uv tool install /path/to/pcdd` or `pipx install /path/to/pcdd`. To upgrade, run `uv tool upgrade pcdd` or `pipx upgrade pcdd`.
55
+
56
+ Then work from the project where you want to use PCDD:
57
+
58
+ ```sh
59
+ cd /path/to/your-project
60
+ pcdd init --dry-run
61
+ pcdd init
62
+ pcdd doctor
63
+ ```
64
+
65
+ `init` installs Codex and Claude Code by default. Select Antigravity with `pcdd init --adapters antigravity`, or combine adapters with commas, such as `--adapters codex,claude,antigravity`. Codex and Antigravity share `AGENTS.md` and the four skills in `.agents/skills/`; Claude Code also uses `CLAUDE.md` and `.claude/skills/`. Review the preview before applying it. Existing installations keep their adapter selection when updated.
66
+
67
+ Without installing, you can run a checkout directly with `python3 /path/to/pcdd/pcdd.py` or add `/path/to/pcdd/bin` to your `PATH`; use `--project /path/to/your-project` before the subcommand to target a project without changing directories.
68
+
69
+ Open a new agent session in the target project and describe the change you want. The installed instructions guide the agent through the appropriate workflow. Configure real project checks before committing; a fresh installation has no gate commands yet.
70
+
71
+ To check the toolkit itself:
72
+
73
+ ```sh
74
+ make ready
75
+ make package-check # builds and installs a wheel in a temporary venv; needs network
76
+ ```
77
+
78
+ See [usage and recovery](USAGE.md), [design](docs/design.md), and the [roadmap](docs/roadmap.md) for details. These project documents are currently in Spanish.
79
+
80
+ PCDD is released under the [MIT License](LICENSE).
81
+
82
+ ## Current scope
83
+
84
+ PCDD v0.4 is an early toolkit. Antigravity installation is covered by CLI tests, with a discovery and continuation pilot in Antigravity CLI. Behavior in the graphical IDE has not been verified; check discovery in the client you use. The CLI manages files and records; the instructions guide agent behavior. It does not technically enforce every workflow rule or guarantee that a model follows it.
85
+
86
+ Task counts measure completed tasks, not effort. Recorded time covers explicitly opened and closed intervals, not necessarily the full development duration. Project checks and human acceptance remain necessary.
@@ -0,0 +1,33 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "pcdd"
7
+ dynamic = ["version"]
8
+ description = "Progressive Change-Driven Development: a local toolkit for working with AI coding agents"
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "aledepaoligampel" }]
14
+ dependencies = []
15
+ classifiers = [
16
+ "Environment :: Console",
17
+ "Programming Language :: Python :: 3",
18
+ ]
19
+
20
+ [project.urls]
21
+ Repository = "https://github.com/aledepaoligampel/pcdd"
22
+
23
+ [project.scripts]
24
+ pcdd = "pcdd_toolkit.cli:main"
25
+
26
+ [tool.setuptools.packages.find]
27
+ where = ["src"]
28
+
29
+ [tool.setuptools.package-data]
30
+ pcdd_toolkit = ["assets/*.md", "assets/skills/*/SKILL.md", "locales/*.json"]
31
+
32
+ [tool.setuptools.dynamic]
33
+ version = { attr = "pcdd_toolkit.__version__" }
pcdd-0.4.0/setup.cfg ADDED
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,100 @@
1
+ Metadata-Version: 2.4
2
+ Name: pcdd
3
+ Version: 0.4.0
4
+ Summary: Progressive Change-Driven Development: a local toolkit for working with AI coding agents
5
+ Author: aledepaoligampel
6
+ License-Expression: MIT
7
+ Project-URL: Repository, https://github.com/aledepaoligampel/pcdd
8
+ Classifier: Environment :: Console
9
+ Classifier: Programming Language :: Python :: 3
10
+ Requires-Python: >=3.9
11
+ Description-Content-Type: text/markdown
12
+ License-File: LICENSE
13
+ Dynamic: license-file
14
+
15
+ # PCDD
16
+
17
+ **Progressive Change-Driven Development**
18
+
19
+ Each change, just enough process.
20
+
21
+ PCDD is a local toolkit for working with AI coding agents. It helps a person and an agent agree on a change, keep enough context to resume it, and verify the result before calling it done.
22
+
23
+ The idea is to add structure as the work needs it. A small, well-understood fix can proceed directly. A substantial change gets approved specifications, tasks, and evidence. A risky change gets independent review and verification before commit approval. Size alone does not determine risk.
24
+
25
+ ## How it works
26
+
27
+ 1. **Understand the request.** The agent reads relevant project context and resolves decisions that affect the work.
28
+ 2. **Define the change.** For substantial work, record verifiable specifications and get approval before implementation.
29
+ 3. **Implement and verify.** Use test-first development when there is a deterministic test and a clear expected result; otherwise record the alternative evidence. Run the project's checks.
30
+ 4. **Keep continuity.** Record tasks, evidence, and the next step in a change document so a new session can pick up the work.
31
+ 5. **Accept the result.** The user tests the outcome before the change is considered complete. Commits and publication follow the project's authorization rules.
32
+
33
+ The starting context stays small: a short core points the agent to relevant instructions and project files. Detailed skills are loaded when needed.
34
+
35
+ ## PCDD, SDD, and ODD
36
+
37
+ These approaches overlap. The comparison below describes their organizing ideas; individual implementations can differ.
38
+
39
+ | Approach | Organizing idea | Practical emphasis |
40
+ | --- | --- | --- |
41
+ | **SDD — Spec-Driven Development** | Use a specification to guide implementation and verification. | Make intended behavior explicit and carry it through planning, code, and checks. |
42
+ | **ODD — Organic Driven Development** | Adapt the workflow to the request and available context. | Handle understood work directly and preserve context for substantial work. |
43
+ | **PCDD — Progressive Change-Driven Development** | Organize work around a change, adding definition and checks as needed. | Use approved specifications for substantial work, independent review for high risk, and local records for continuation and acceptance. |
44
+
45
+ PCDD uses specifications and adapts process to the work. Its concrete choices are a local CLI, Markdown change records, project-owned gates, and agent skills. It does not require an external memory service or a particular application stack. No comparative token, speed, or quality advantage has been established.
46
+
47
+ ## What's included
48
+
49
+ - **Codex, Claude Code, and Antigravity adapters**, installed in the target project.
50
+ - **Four skills:** `pcdd-work`, `pcdd-review`, `pcdd-commit`, and `pcdd-commit-review`.
51
+ - **Installation and maintenance:** preview changes, check an installation, update managed files, and recover or roll back transactions.
52
+ - **Change records:** specifications, task states, verification evidence, and continuation notes.
53
+ - **Progress and time:** task counts and explicitly recorded work intervals, available as human-readable output or JSON.
54
+ - **English and Spanish CLI output.** Agent responses follow the user's language; project documents follow the project's conventions.
55
+
56
+ ## Try it
57
+
58
+ Requires **Python 3.9+**, with no runtime dependencies. PCDD is not published to a package registry yet; install it from the Git repository with [uv](https://docs.astral.sh/uv/) (recommended) or [pipx](https://pipx.pypa.io/). Both put the `pcdd` command on your `PATH` in an isolated environment:
59
+
60
+ ```sh
61
+ uv tool install pcdd --from git+https://github.com/aledepaoligampel/pcdd
62
+ # or
63
+ pipx install git+https://github.com/aledepaoligampel/pcdd
64
+ ```
65
+
66
+ If you don't have uv, install it with `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh` (see the [uv installation guide](https://docs.astral.sh/uv/getting-started/installation/) for Windows and other options). For pipx, use `brew install pipx && pipx ensurepath`. Open a new terminal afterwards so `pcdd` is on your `PATH`.
67
+
68
+ You can also install from a local checkout with `uv tool install /path/to/pcdd` or `pipx install /path/to/pcdd`. To upgrade, run `uv tool upgrade pcdd` or `pipx upgrade pcdd`.
69
+
70
+ Then work from the project where you want to use PCDD:
71
+
72
+ ```sh
73
+ cd /path/to/your-project
74
+ pcdd init --dry-run
75
+ pcdd init
76
+ pcdd doctor
77
+ ```
78
+
79
+ `init` installs Codex and Claude Code by default. Select Antigravity with `pcdd init --adapters antigravity`, or combine adapters with commas, such as `--adapters codex,claude,antigravity`. Codex and Antigravity share `AGENTS.md` and the four skills in `.agents/skills/`; Claude Code also uses `CLAUDE.md` and `.claude/skills/`. Review the preview before applying it. Existing installations keep their adapter selection when updated.
80
+
81
+ Without installing, you can run a checkout directly with `python3 /path/to/pcdd/pcdd.py` or add `/path/to/pcdd/bin` to your `PATH`; use `--project /path/to/your-project` before the subcommand to target a project without changing directories.
82
+
83
+ Open a new agent session in the target project and describe the change you want. The installed instructions guide the agent through the appropriate workflow. Configure real project checks before committing; a fresh installation has no gate commands yet.
84
+
85
+ To check the toolkit itself:
86
+
87
+ ```sh
88
+ make ready
89
+ make package-check # builds and installs a wheel in a temporary venv; needs network
90
+ ```
91
+
92
+ See [usage and recovery](USAGE.md), [design](docs/design.md), and the [roadmap](docs/roadmap.md) for details. These project documents are currently in Spanish.
93
+
94
+ PCDD is released under the [MIT License](LICENSE).
95
+
96
+ ## Current scope
97
+
98
+ PCDD v0.4 is an early toolkit. Antigravity installation is covered by CLI tests, with a discovery and continuation pilot in Antigravity CLI. Behavior in the graphical IDE has not been verified; check discovery in the client you use. The CLI manages files and records; the instructions guide agent behavior. It does not technically enforce every workflow rule or guarantee that a model follows it.
99
+
100
+ Task counts measure completed tasks, not effort. Recorded time covers explicitly opened and closed intervals, not necessarily the full development duration. Project checks and human acceptance remain necessary.
@@ -0,0 +1,26 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/pcdd.egg-info/PKG-INFO
5
+ src/pcdd.egg-info/SOURCES.txt
6
+ src/pcdd.egg-info/dependency_links.txt
7
+ src/pcdd.egg-info/entry_points.txt
8
+ src/pcdd.egg-info/top_level.txt
9
+ src/pcdd_toolkit/__init__.py
10
+ src/pcdd_toolkit/__main__.py
11
+ src/pcdd_toolkit/cli.py
12
+ src/pcdd_toolkit/presentation.py
13
+ src/pcdd_toolkit/assets/change.md
14
+ src/pcdd_toolkit/assets/core.md
15
+ src/pcdd_toolkit/assets/skills/pcdd-commit/SKILL.md
16
+ src/pcdd_toolkit/assets/skills/pcdd-commit-review/SKILL.md
17
+ src/pcdd_toolkit/assets/skills/pcdd-review/SKILL.md
18
+ src/pcdd_toolkit/assets/skills/pcdd-work/SKILL.md
19
+ src/pcdd_toolkit/locales/en.json
20
+ src/pcdd_toolkit/locales/es.json
21
+ tests/test_antigravity.py
22
+ tests/test_cli.py
23
+ tests/test_colors.py
24
+ tests/test_commit_skills.py
25
+ tests/test_experience.py
26
+ tests/test_packaging.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ pcdd = pcdd_toolkit.cli:main
@@ -0,0 +1 @@
1
+ pcdd_toolkit
@@ -0,0 +1,2 @@
1
+ """PCDD: local, dependency-free project workflow kit."""
2
+ __version__ = '0.4.0'
@@ -0,0 +1,3 @@
1
+ from .cli import main
2
+
3
+ main()
@@ -0,0 +1,25 @@
1
+ # {{name}}
2
+
3
+ <!-- Write project content in its agreed language, or the user's language if none is set.
4
+ Preserve original quotations verbatim. Keep the Tasks heading and task syntax unchanged:
5
+ the CLI parses them. Other headings may follow project conventions. -->
6
+
7
+ ## Specs
8
+
9
+ <!-- S1: original user quotation, behavior, and verifiable acceptance criterion. -->
10
+
11
+ ## Tasks
12
+
13
+ - [ ] T1 (S1) Define and approve scope
14
+
15
+ ## Evidence
16
+
17
+ No evidence yet.
18
+
19
+ ## Continuation
20
+
21
+ Next step: define specs. Stage: definition. Human acceptance: pending.
22
+
23
+ ## Log
24
+
25
+ <!-- L1: verbatim request. Record actual approvals. -->
@@ -0,0 +1,18 @@
1
+ # PCDD — Progressive Change-Driven Development
2
+
3
+ Each change, just enough process. Project-specific instructions override these defaults within the agent's constraints. This does not authorize external effects or expand the user's request.
4
+
5
+ The kit's instructions and source templates are maintained in English. Respond in the user's language and write project documents in the project's agreed language, falling back to the user's language if none is established. Preserve original quotations and approvals verbatim. Keep command names, identifiers, and machine-parsed syntax unchanged; the CLI language setting controls terminal output only.
6
+
7
+ 1. Understand the request and discover context before asking the user for paths: inspect relevant files and locate project instructions, overview, planning, continuation notes, and manifests where available. Read only what the request needs. Do not require a particular context filename or load the entire history. If several active efforts fit the request, ask which one to continue. Questions and research do not authorize implementation. Well-understood, bounded work that can be resumed from the diff proceeds directly, without a separate change document or routine delegation. Assess risk independently of size.
8
+ 2. For substantial work, read the `pcdd-work` skill installed for your agent. Use a document at `pcdd/changes/<name>.md`. Do not load all changes or their history at startup; resume from the continuation section and relevant specs/tasks. For requests to save progress or continue where work stopped, consult `pcdd-work` to preserve or recover the continuation point without loading the entire history. Recognize these requests in the user's language and preserve existing section names, including `Continuación` in older documents.
9
+ 3. Before implementing a change, present verifiable specs with the user's quotations and wait for approval. Record the actual approval. Do not request approval again when already granted. An extension requires approval only for the new scope.
10
+ 4. Use test-first development when a deterministic test and clear expected result exist: observe RED, GREEN, then refactor. Verify behavior through public interfaces. Otherwise explain the alternative evidence and what remains unverified.
11
+ 5. Identify risk: (1) persisted data or irreversible effects; (2) security; (3) external contracts; (4) concurrency; (5) delivery/environment; (6) lack of coverage; (7) money/tax. Use `Risk: none` or `Risk: item N (reason)`. Prefer a coherent unit over an artificial 400-line split.
12
+ 6. Before committing, run the gate configured in `.pcdd/config.json` and the database gate if applicable. If empty, investigate existing scripts and tools and configure real commands during authorized work, preserving the project's settings. If no application exists yet, define gates with its first scaffold and tests; do not use benchmarks as the product gate or invent commands. Ask only when a real decision is unresolved. Empty does not mean passed. High risk also requires `pcdd-review`, code review and independent verification after the gate, and human approval based on an understandable summary. For small risky work, create a minimal record of criteria, evidence, and approval.
13
+ 7. For work tracked in a change, check the current session's exposed tools for native task tracking. When available, use them to mirror the change's tasks at startup/resumption and after state changes; preserve PCDD task IDs in labels and derive all states from the document. Update the document first; the native view is not a second plan. If the tools are absent or cannot represent the state, explain the limitation at startup or when encountered; do not claim text lists are native tasks. Also show a brief chat block when starting or resuming and when task status changes: completed count, relevant completed tasks, active task, and next step or blocker. During long operations, explain what is still running and what remains unknown without inventing progress. Use the CLI for task counts and measured time; show the confirmed closed duration when closing a work interval. Do not invent durations, savings, or ETAs. Close the interval before waiting for the user. Do not estimate the missing time of an interrupted session.
14
+ 8. The user tests the result before the change is declared done. Completed tasks do not imply acceptance. Push, PR, merge, and publication require explicit instructions; commits follow the project's authorization rules.
15
+
16
+ For Git commits, use `pcdd-commit`; to organize pending changes into coherent commits, use `pcdd-commit-review`. These skills do not replace the high-risk review checkpoint. Review-only requests do not authorize index or history changes. Whether or not a commit skill is loaded, preserve the user's Git identity and never add `Co-Authored-By` trailers, textual signatures, or AI attribution to commits or PR descriptions. Respect the project's cryptographic signing configuration and hooks; cryptographic signatures are not AI attribution.
17
+
18
+ Configuration belongs to the project. Do not customize managed core or skill files; use `AGENTS.md` and `.pcdd/config.json`. PCDD requires no external memory, MCP, or particular editor.
@@ -0,0 +1,30 @@
1
+ ---
2
+ name: pcdd-commit
3
+ description: Create a coherent Git commit within the user's authorized scope, preserving unrelated work and staging. Use for commit requests or explicit invocation; a review-only request does not authorize Git writes.
4
+ ---
5
+
6
+ # PCDD Commit
7
+
8
+ Read the current checkout's project instructions and `.pcdd/core.md`, unless already loaded. Discover applicable commit conventions and gate commands from that project; do not assume a package manager, directory layout, or separate command file. Resolve the root with `git rev-parse --show-toplevel` and work in that checkout, including worktrees.
9
+
10
+ ## Scope and authorization
11
+
12
+ An explicit invocation or request to commit authorizes commits within the stated scope. Present the message and paths as an informative update and proceed without asking for equivalent approval again. An explicit push request may include preparing necessary commits for the named work, subject to project rules; preserve its specified destination. A commit request alone never authorizes push, PR, merge, or publication.
13
+
14
+ PCDD's high-risk control still applies: the candidate must pass its gate, receive code review and independent verification through `pcdd-review`, and receive human approval of the risk summary before committing. General commit authorization or spec approval does not replace that checkpoint. Preserve an approval already granted for the same candidate and scope.
15
+
16
+ If the request is only to review or propose, return findings without changing the index or history. If scope is ambiguous, inspect first and ask only about the unresolved part. Do not infer ownership or include another effort merely because it is dirty or staged.
17
+
18
+ ## Prepare and commit
19
+
20
+ 1. Inspect status, complete staged and unstaged diffs, and relevant untracked files. Check Git author and committer identity without replacing it with an agent identity. If identity is missing or inconsistent with the requested author, resolve that before committing; do not invent it.
21
+ 2. Confirm that the changes express one coherent intent. If they need multiple commits, use `pcdd-commit-review`; the existing authorization remains valid for the same scope. Include related tests and documentation with each unit. Do not force a split by line count.
22
+ 3. Run the project's applicable gates for the candidate, including its database gate when required. Existing evidence is reusable only if it covers this candidate and project rules allow it. Do not bypass failures, label missing checks as passed, or substitute an unrelated benchmark. Apply the high-risk checkpoint when relevant.
23
+ 4. Exclude secrets, real environment files, private keys/certificates, generated dependencies, builds, and scratch files unless the project intentionally tracks an appropriate non-secret artifact. Review example environment files for real credentials. Preserve unrelated files and staged changes.
24
+ 5. Follow the project's commit convention. If none exists, use English Conventional Commits: `type(scope): imperative description`, with a subject no longer than 72 characters and an optional body explaining why. Use an existing meaningful scope; do not invent a fixed module catalog. Reference the actual change document and task/spec IDs when relevant, without inventing them.
25
+ 6. Show the message and included paths. Stage explicit paths or selected hunks, never indiscriminately run `git add .` or `git add -A`. A path can contain both authorized and unrelated edits: preserve those hunks and any pre-existing staging. Isolate the candidate safely; ask about the affected scope if that cannot be done without losing or including unrelated staging.
26
+ 7. Review the entire candidate index and staged diff before committing. Keep the user's Git identity. Never add `Co-Authored-By` trailers, textual signatures, or AI attribution to commit messages or PR descriptions. Do not rewrite unrelated messages or history to enforce this on earlier commits.
27
+ 8. Write the message literally to a temporary file and use `git commit -F <message-file>`, with no shell expansion of its contents. Respect configured cryptographic signing and hooks: do not disable signing, change persistent Git configuration, or bypass hooks to make a commit succeed. A signing or hook failure is a concrete blocker to resolve, not permission to bypass it.
28
+ 9. Inspect the resulting commit's message, author/committer, and changed paths, then check remaining status and staging. Report its hash, summary, checks, and remaining work. If a hook changed the result unexpectedly, explain it and resolve within authorization; do not silently amend or reset history. Push only when explicitly authorized, to the specified destination; no force-push or history rewriting without specific authorization.
29
+
30
+ If no changes remain in scope, report that without creating an empty commit. Do not impose a PR, new branch, model switch, or routine delegation. Distinguish missing user authorization from an actual sandbox restriction. Respond in the user's language; follow the project's language convention for the commit message.
@@ -0,0 +1,21 @@
1
+ ---
2
+ name: pcdd-commit-review
3
+ description: Review pending Git changes and organize them into coherent commits by intent and dependency. Use for organizing commits or explicit invocation; honor review-only requests without changing the index or history.
4
+ ---
5
+
6
+ # PCDD Commit Review
7
+
8
+ Read the current checkout's project instructions, `.pcdd/core.md`, and the installed `pcdd-commit` skill unless already loaded. The commit skill defines identity, attribution, signing, gates, and authorization rules for each resulting commit. Resolve paths from this checkout, including worktrees; there is no dependency on another repository's commands or conventions.
9
+
10
+ This skill organizes commits. `pcdd-review` provides independent code review and verification for high-risk changes; organizing the diff does not replace that control.
11
+
12
+ An explicit invocation authorizes organizing and creating commits within its stated scope, unless the user restricts the request to review or a proposal. In that case, inspect and return the plan without changing files, the index, or history. An ordinary request to review code alone does not authorize commits. Preserve prior authorization; do not ask to approve the same plan again merely because it contains several commits. High-risk approval remains a separate required checkpoint.
13
+
14
+ 1. Inspect status, full staged and unstaged diffs, and relevant new files. Identify the authorized work; existing staging does not establish ownership or inclusion. Ask only about ambiguity that affects scope, and continue independent authorized work where possible.
15
+ 2. Group changes by intent and dependencies. Each unit should make sense independently and contain its relevant tests and docs. Isolate high-risk work from unrelated changes; do not split a necessary dependency into a broken intermediate state or impose a line-count quota. A coherent initial scaffold can be one commit.
16
+ 3. Present a numbered plan with each proposed message, paths or hunks, dependencies, and exclusions. Use the project's commit convention or the English Conventional Commits default from `pcdd-commit`. If only review was requested, stop here without staging or committing.
17
+ 4. Order prerequisites before their consumers. Validate the actual candidate for each commit according to the project gates. A passing final working tree alone does not prove that an intermediate commit works. Reuse evidence only when it covers that candidate and project rules allow it; do not repeat costly tests without a change or unresolved concern.
18
+ 5. Execute each authorized unit through the `pcdd-commit` workflow, preserving unrelated staging and work. Keep the user's identity; never add `Co-Authored-By`, textual signatures, or AI attribution. Respect cryptographic signing and hooks. Complete `pcdd-review` and obtain the required risk approval before any high-risk commit; do not simulate an independent review yourself.
19
+ 6. Verify the resulting sequence, messages, paths, and remaining status against the plan. Report hashes and exclusions. Push only with explicit authorization and to its specified destination. On divergence, inspect and report the situation; do not force-push, rebase, or overwrite remote work without the required authorization.
20
+
21
+ Do not impose a PR, new branch, model switch, or routine subagents. Respond in the user's language. Ask only about unresolved scope, unauthorized destructive actions, required high-risk approval, or concrete environment blockers.
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: pcdd-review
3
+ description: Independently review and verify a high-risk PCDD change after its gate passes and before requesting commit approval. Also supports explicit review requests without authorizing external writes.
4
+ ---
5
+
6
+ # PCDD Review
7
+
8
+ The implementer first confirms that the candidate passes its gate. Do not launch reviews before that. The environment must provide code review and an independent verifier agent; if a capability is missing, report it and stop the high-risk commit. Do not simulate independence through self-review.
9
+
10
+ Follow the language policy in `.pcdd/core.md`: use the user's language for summaries, the project's agreed language for documents, and preserve original quotations verbatim. Keep the `PASS` and `CHANGES` verdicts unchanged.
11
+
12
+ The implementer prepares two bounded assignments: code review and public-interface verification. Use the native review command when available, otherwise a separate reviewer. Do not assume `/code-review` exists in every client.
13
+
14
+ Both receive only relevant specs, risk items, the diff including new files, conventions, and required commands. The verifier starts with fresh context, without Log, the implementer's narrative, or previous conclusions. There is no need to reread the entire history.
15
+
16
+ ## Verifier assignment
17
+
18
+ - Try to demonstrate that a criterion is not met. Run targeted public-interface checks: HTTP, exit codes, output, or observable effects; reading code alone does not demonstrate behavior.
19
+ - Do not rerun the entire suite that already passed. Select edge cases relevant to the risk and regression tests for affected contracts.
20
+ - Do not modify existing files, configuration, or user data; use an isolated environment. You may deliver new tests in separate files for the implementer to evaluate.
21
+ - No cloud access, deployments, publications, stopping others' processes, or Git write operations.
22
+ - Return `PASS` or `CHANGES`, evidence per S#, reproducible findings, new tests, and limitations. A criterion without evidence remains unverified, not approved.
23
+
24
+ ## Review closure
25
+
26
+ The implementer fixes findings and revalidates the final candidate. Adding tests or changing code requires rerunning the gate; material changes return to the relevant reviewer. An earlier review does not cover new changes.
27
+
28
+ Present a summary that does not require the user to read code: what changes, what could fail, what both reviews found, what was fixed, and what remains unverified. Wait for approval and record its quotation before committing. That approval does not authorize push or publication.
@@ -0,0 +1,59 @@
1
+ ---
2
+ name: pcdd-work
3
+ description: Define, implement, or resume a substantial change in a PCDD project, preserving specs, tasks, and evidence across sessions. Also handles requests to save progress or continue where work stopped, in the user's language.
4
+ ---
5
+
6
+ # PCDD Work
7
+
8
+ Consult `.pcdd/core.md` if you have not read it yet. Do not reread the entire project. Use `--json` to consume CLI results, for example `pcdd --json time status <name>`; human output is not a parsing contract.
9
+
10
+ Follow the language policy in the core: respond in the user's language, write project content in its agreed language, and preserve quotations verbatim. Recognize save/resume requests by meaning in the user's language; no exact phrase is required. Translate user-facing examples below as appropriate. Keep `## Tasks`, task IDs, state markers, and command syntax unchanged because the CLI parses them. Preserve existing document headings; the continuation section may be called `Continuation`, `Continuación`, or the project's equivalent.
11
+
12
+ - If no change exists yet, recover scope from relevant documentation discovered through the core. A brief is context, not automatic approval: distinguish confirmed decisions from proposals before drafting specs. Do not require a fixed filename or ask again for information already documented.
13
+ - Identify the change in the roadmap if one exists. The roadmap tracks feature status; the change document tracks tasks. Do not create a roadmap just to duplicate a document.
14
+ - Create the document with `pcdd new <name>` (or `python3 /path/to/pcdd.py new <name>` if the CLI is not on PATH). The path resolves from the target project. Adapt the new template's prose to the project's language; do not rewrite existing documents merely to match the English template.
15
+ - Specs S#: original quotation, verifiable behavior, and acceptance criterion. Identify agent proposals; do not attribute them to the user. Adopt inherited rules explicitly.
16
+ - Before coding, obtain approval for new specs and record the quotation in Log. Link tasks to S#, with evidence and a commit when one exists. Do not invent hashes.
17
+ - Task format: `- [ ] T1 (S1) description`. States: space for pending, `>` in progress, `!` blocked, `x` completed. IDs must be unique. Keep only tasks in `## Tasks`; put detailed evidence in the evidence section.
18
+ - Complete a task when it meets its criterion and has evidence. Explain scope when tasks are added; a changed denominator does not automatically mean regression.
19
+ - Track time with `pcdd time start <name>`. Use `pause` or `stop` to close the interval before waiting for a reply or ending the turn. Tests and builds count as work; human waiting does not. Each start is an interval, not necessarily a chat session.
20
+ - On resuming, consult `pcdd time status <name>`. If an interval from another session remains open and its end is unknown, use `abandon`, not `stop`: it remains incomplete and excluded from the total. Do not estimate missing time. Then start a new interval.
21
+ - Check the tools exposed in the current session for native task tracking, such as `update_plan` or Claude Code's `TaskCreate`, `TaskUpdate`, and `TaskList`. Use available tools at startup/resumption and after task state changes to mirror the change document, updating the document first. Preserve the PCDD IDs in task labels even when the client assigns its own IDs. Reconcile existing entries for this change instead of duplicating them; preserve unrelated tasks. Native task entries are a derived view, never an independent plan. Map only supported states faithfully; if a state such as blocked has no native equivalent, keep the exact state and blocker explicit in the label or description. Do not mark a blocked task completed to fit the client.
22
+ - If native tools are absent, report at startup that progress will be shown in text. If a native update fails, report that limitation and continue with the document and chat block. Do not invent tools, equate Markdown lists with a native panel, or use goals, new sessions, background jobs, or external trackers as substitutes. Do not change client settings automatically. Tool calls verify task operations; visual rendering requires an interactive client check.
23
+ - When starting or resuming and whenever task status changes, show a brief, separate progress block. Use a heading such as `**PCDD** · 4/6 tasks completed`, followed by a few short lines with task IDs, concise descriptions and explicit states (completed, in progress, pending, blocked). Include relevant completed tasks, the active task or tasks, and the next step or blocker. For a long task list, show only the relevant subset; the CLI count still covers all tasks. If no task is active, say what is pending, including human acceptance when appropriate. Update the change document first and obtain the count through the CLI. Its Tasks section is the source of truth; never maintain a second independent plan in chat or client tools.
24
+ - During long operations, give occasional short updates naming the active task, what is still running, and what result or check is still pending. Do not invent intermediate percentages, repeat the full block for every command, or imply success before evidence arrives. Explain blockers plainly and name the next action that can resolve them. User-facing updates must not depend on a particular client's task UI.
25
+ - When closing a work interval, append the confirmed closed total to the block heading, for example `**PCDD** · 4/6 tasks completed · 18 min`. Use minutes and seconds when useful; do not invent unmeasured time. Omit timer status and recording details such as “recorded since the timer started” or “timer paused”. Explain missing or incomplete timing separately only when it materially affects the result. Do not confuse task counts with effort, ETAs or final acceptance.
26
+ - Before pausing, update the continuation section with the next step, blocker, and current evidence. Preserve original decisions in Log; consult it only to resolve uncertainty.
27
+ - At delivery, report behavior, validation, residual risks, recorded time and incomplete intervals, and human testing steps. Keep acceptance pending until the user tests and confirms.
28
+
29
+ If the CLI is missing or fails, report it; do not invent metrics or download tools automatically. Tasks can be maintained in Markdown while the limitation is resolved.
30
+
31
+ Example of a mid-work update (illustrative counts and tasks; translate for the user):
32
+
33
+ **PCDD** · 3/5 tasks completed
34
+
35
+ - Completed · T3 · Isolated proxy and measurement.
36
+ - In progress · T4 · Run comparison suite.
37
+ - Pending · T5 · Review results and prepare delivery.
38
+
39
+ The pilot passed. The comparison suite is still running; equivalence checks remain pending.
40
+
41
+ ## Save progress
42
+
43
+ Keep the continuation section current when closing a unit of work; do not wait until context is exhausted. When the user asks to save progress, save a resumption point in the change document. If none exists and work must persist across sessions, create a minimal record using the project's format.
44
+
45
+ - Leave a short account of the current task and concrete next action; implemented versus verified work; blockers; relevant specs and references to recorded approvals. Preserve quotations in Log without duplicating or reinterpreting them.
46
+ - Record relevant modified files, branch/commit if available, checks run, and the state they covered. Distinguish uncommitted work from others' changes; do not invent ownership or hashes.
47
+ - Include discarded attempts only when they prevent repeating a mistake, and your own active processes if they affect continuation. Do not copy the conversation, secrets, or complete tool output.
48
+ - Close the known time interval before finishing; do not complete tasks or create commits merely to save progress. If saving or closing the timer fails, report what was not persisted.
49
+ - Verify that the document was saved. Identify the change and say, in the user's language: “Progress saved. You can open a new session and ask: ‘Continue where we left off.’” Include the change name in that phrase if several efforts are active.
50
+
51
+ ## Continue where work stopped
52
+
53
+ - Identify the requested change. Use it if only one is active; ask which one if several are plausible. Do not choose solely by file date or read every Log.
54
+ - Read the continuation section, relevant tasks, and their specs. Consult referenced evidence or approvals only when needed.
55
+ - Compare the note with files, the diff, and Git status if available. Reconcile subsequent changes without overwriting them; ask only about contradictions that affect scope or authorization. Do not treat a test on different code as current evidence.
56
+ - Check the timer: abandon a previous interval with no known end as incomplete, never add estimated time. Start a new interval when work resumes.
57
+ - Preserve previous approvals and continue with the next action within their scope. Do not restart planning or ask to approve the same work again. Saving progress did not authorize new work.
58
+
59
+ The agent may suggest switching sessions at a stable point if the conversation has accumulated irrelevant context. Do not assume access to a context percentage or promise to open a new session automatically. These phrases are requests to the agent, not CLI subcommands.