@svayam-opensource/prj 0.5.1 → 0.5.2
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.
- package/README.md +65 -101
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,123 +1,87 @@
|
|
|
1
|
-
# Agentic Development Framework
|
|
1
|
+
# `prj` — Governance Actions for the Agentic Development Framework
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
3
|
+
`@svayam-opensource/prj` is the **client you run to take governed actions** on
|
|
4
|
+
your projects — start work, assign owners, create tasks, finish — entirely on top
|
|
5
|
+
of GitHub, under your organization's policy. You run `prj` and follow the menus;
|
|
6
|
+
**you don't need to memorize commands.**
|
|
6
7
|
|
|
7
8
|
---
|
|
8
9
|
|
|
9
|
-
##
|
|
10
|
-
|
|
11
|
-
Agentic development gets messy fast: agents make decisions, modify multiple repos in parallel, propose policy updates, and accumulate institutional knowledge. Most teams handle this with ad-hoc convention; that breaks down past a handful of projects or a few agents.
|
|
10
|
+
## The framework has two components
|
|
12
11
|
|
|
13
|
-
|
|
12
|
+
```mermaid
|
|
13
|
+
flowchart LR
|
|
14
|
+
subgraph F["Governed Agentic Development Framework"]
|
|
15
|
+
C["Governance Content<br/>policies · knowledge structure · agent harness<br/>(the rules & scaffolding)"]
|
|
16
|
+
A["Governance Actions<br/>prj — this package<br/>(the client that acts)"]
|
|
17
|
+
end
|
|
18
|
+
C -->|"1 - adopt & configure FIRST"| W[("Your governance<br/>workspace")]
|
|
19
|
+
A -->|"2 - then act on it"| W
|
|
20
|
+
```
|
|
14
21
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
22
|
+
1. **Governance Content** — the policies, knowledge structure, agent harness, and
|
|
23
|
+
scaffolding that define *how* your org governs agentic work. **This lives in the
|
|
24
|
+
template repo** — adopt and refresh it there:
|
|
25
|
+
👉 **https://github.com/svayam-opensource/governed-agentic-dev-framework**
|
|
26
|
+
2. **Governance Actions** — **this package (`prj`)**: the client you run to *take*
|
|
27
|
+
governed actions on your projects. **This README covers the Actions.**
|
|
21
28
|
|
|
22
29
|
---
|
|
23
30
|
|
|
24
|
-
##
|
|
25
|
-
|
|
26
|
-
> This is a **template repository.** You don't fork it — you use it to scaffold *your own* private workspace repo, which you then own and commit to. The framework's `publish` upstream stays clean; your private overlay (real projects, accumulated knowledge, your `org-config.yaml` values) lives only in your repo.
|
|
27
|
-
|
|
28
|
-
**1. Create your repo from the template.** Open the framework's repo on GitHub:
|
|
29
|
-
|
|
30
|
-
> https://github.com/svayam-opensource/governed-agentic-dev-framework
|
|
31
|
-
|
|
32
|
-
Click the green **"Use this template"** button → **"Create a new repository"**. Pick a name (e.g. `000-acme-prj`) and visibility (typically Private). GitHub will create a new repository under your account or org.
|
|
31
|
+
## Governance Actions (`prj`)
|
|
33
32
|
|
|
34
|
-
|
|
33
|
+
### Purpose
|
|
34
|
+
One client for the whole governed project lifecycle on GitHub. Instead of
|
|
35
|
+
hand-managing boards, branches, and issues, you run `prj`, pick what you want to
|
|
36
|
+
do, and it performs the action under policy — keeping ownership, status, and
|
|
37
|
+
history consistent. The goal is *not* for you to learn every command — just to
|
|
38
|
+
**run `prj` and follow the journeys** below.
|
|
35
39
|
|
|
40
|
+
### Install
|
|
36
41
|
```bash
|
|
37
|
-
|
|
38
|
-
git clone https://github.com/<your-github-org>/<your-new-repo>.git
|
|
39
|
-
cd <your-new-repo>
|
|
40
|
-
|
|
41
|
-
# Verify the toolchain (git, gh, python3, pyyaml; yq optional).
|
|
42
|
-
# Hard gate — refuses to proceed if anything required is missing.
|
|
43
|
-
bash scripts/install-deps.sh
|
|
44
|
-
|
|
45
|
-
# Configure the framework for your org and verify GitHub access.
|
|
46
|
-
# Interactive: prompts for org name, slug, role identities, etc., with
|
|
47
|
-
# sensible defaults detected from gh and git config. Substitutes
|
|
48
|
-
# throughout, then checks gh user / org membership / scopes.
|
|
49
|
-
bash setup.sh
|
|
50
|
-
|
|
51
|
-
# (Optional) Customize the policy text for your org.
|
|
52
|
-
$EDITOR knowledge/policies/agentic-development-policy.md
|
|
53
|
-
|
|
54
|
-
# Commit and push to YOUR repository.
|
|
55
|
-
git add -A
|
|
56
|
-
git commit -m "configure framework for <your-org>"
|
|
57
|
-
git push origin main
|
|
58
|
-
|
|
59
|
-
# Start using it.
|
|
60
|
-
./prj
|
|
42
|
+
npm i -g @svayam-opensource/prj
|
|
61
43
|
```
|
|
44
|
+
Runtime prerequisites (not npm dependencies — `prj` is bash): `bash`, `git`,
|
|
45
|
+
`gh` (authenticated), `yq`, `python3`. On Windows, run inside **Git Bash**.
|
|
62
46
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
| Doc | For |
|
|
84
|
-
|---|---|
|
|
85
|
-
| [README](README.md) | First-time visitor — what this is, do you want it |
|
|
86
|
-
| [docs/USER_GUIDE.md](docs/USER_GUIDE.md) | Reference — concepts, roles, CLI surface |
|
|
87
|
-
| [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md) | Day-in-the-life — step-by-step working on a project, prompting the agent |
|
|
88
|
-
| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor — proposing changes to the framework itself |
|
|
89
|
-
| [SECURITY.md](SECURITY.md) | Security reporter |
|
|
90
|
-
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
|
|
91
|
-
| [knowledge/policies/agentic-development-policy.md](knowledge/policies/agentic-development-policy.md) | The policy itself — read this once you've adopted |
|
|
92
|
-
|
|
93
|
-
---
|
|
47
|
+
### Sequencing — Content first, then Actions
|
|
48
|
+
```mermaid
|
|
49
|
+
flowchart LR
|
|
50
|
+
S1["Adopt Governance Content<br/>(template repo → setup)"] --> S2["Configure your workspace<br/>(org-config.yaml)"] --> S3["Run prj — take Actions"]
|
|
51
|
+
```
|
|
52
|
+
`prj` acts *on* a configured governance workspace. **Set up Governance Content
|
|
53
|
+
first** (from the template repo), **then** use `prj`. Run `prj` from anywhere
|
|
54
|
+
inside the workspace (it finds it via `$ADF_WORKSPACE` or the nearest
|
|
55
|
+
`org-config.yaml`).
|
|
56
|
+
|
|
57
|
+
### Dependencies — GitHub is the substrate
|
|
58
|
+
`prj` keeps no separate database. Every fact lives in GitHub:
|
|
59
|
+
```mermaid
|
|
60
|
+
flowchart TD
|
|
61
|
+
P["prj"] --> GP["GitHub Projects<br/>a board IS a project<br/>(ownership & status live here)"]
|
|
62
|
+
P --> GI["Issues<br/>units of work<br/>(the anchor issue carries ownership)"]
|
|
63
|
+
P --> GR["Repos<br/>where code lives<br/>(derived from the board's issues)"]
|
|
64
|
+
P --> GA["GitHub Actions<br/>CI gates that enforce the policy"]
|
|
65
|
+
```
|
|
94
66
|
|
|
95
|
-
|
|
67
|
+
### Journeys — *how do I…?*
|
|
68
|
+
You don't need the command list. Run **`prj`** and follow the menu (every step is
|
|
69
|
+
back-navigable — pick `0) ← back` anytime). Common paths:
|
|
96
70
|
|
|
97
|
-
|
|
|
71
|
+
| I want to… | Do this |
|
|
98
72
|
|---|---|
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
| `scripts/onboard-repo.sh` | Bring an existing code repo under the framework |
|
|
107
|
-
| `scripts/test-merge.sh` | Local pre-merge validator (used by lifecycle scripts) |
|
|
108
|
-
| `scripts/validate/run.py` | Schema/registry/lifecycle/cross-ref validators |
|
|
109
|
-
| `scripts/sync-from-publish.sh` | Pull universal updates from the framework's upstream branch |
|
|
110
|
-
|
|
111
|
-
---
|
|
73
|
+
| **See the projects** | `prj` → **list** (ongoing) — or `prj manage list-all` for the full board universe |
|
|
74
|
+
| **Assign a project / set its owner** | `prj manage` → **Project** → owners → **add** (grants board access + marks the anchor issue's owner) |
|
|
75
|
+
| **Start working on a project** | `prj work` → **pick the project** → it ensures the project is set up and **opens it in your agent**, with the session-start protocol already running |
|
|
76
|
+
| **Start a task** (parallel work on an issue) | `prj work` → pick project → **New branch** → pick the issue(s) |
|
|
77
|
+
| **Continue existing work** | `prj work` → pick project → **Existing branch** → pick it |
|
|
78
|
+
| **Finish a task / close a project** | `prj work` → pick project → pick the branch → **Finish** (merges the task, or closes the project through the governance gate) |
|
|
79
|
+
| **Propose a policy or knowledge change** | `prj knowledge` |
|
|
112
80
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
This framework is in active use at the upstream maintainer org and is offered as-is for other organizations to adopt. Issues and PRs are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
81
|
+
> Fuller, step-by-step journeys live in the framework's knowledge base under
|
|
82
|
+
> **paths / development procedures** (see the template repo).
|
|
116
83
|
|
|
117
84
|
---
|
|
118
85
|
|
|
119
86
|
## License
|
|
120
|
-
|
|
121
|
-
MIT — see [LICENSE](LICENSE).
|
|
122
|
-
|
|
123
|
-
Copyright (c) 2026 Svayam Infoware Private Limited and contributors.
|
|
87
|
+
MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Svayam Infoware Private Limited and contributors.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@svayam-opensource/prj",
|
|
3
|
-
"version": "0.5.
|
|
3
|
+
"version": "0.5.2",
|
|
4
4
|
"description": "Governed Agentic Development Framework CLI (prj). A bash CLI wrapped for npm; operates on a governance workspace resolved via $ADF_WORKSPACE or the nearest org-config.yaml. Runtime prerequisites (not npm deps): bash, git, gh, yq, python3 (use Git Bash on Windows).",
|
|
5
5
|
"bin": {
|
|
6
6
|
"prj": "bin/prj"
|