Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 4 additions & 5 deletions .agent/skills/bootstrap-clever-work/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,13 +34,12 @@ Use this local folder layout unless the user has explicitly provided another pat
clever-agent-project/
clever-context-monorepo/
clever-change-control/
projects/
<target-repo>/
<target-repo>/
```

The three agent/control-plane repositories stay under `<CLEVER_ROOT>/clever-agent-workspace/`.
Remote product/service repositories are cloned or pulled under
`<CLEVER_ROOT>/projects/<target-repo>/`. Seed files are copied
`<CLEVER_ROOT>/<target-repo>/`. Seed files are copied
into that target repo root.

- `AGENTS.md`: agent execution procedure, working order, issue/branch rules, verification, context update checks, and completion conditions
Expand Down Expand Up @@ -71,7 +70,7 @@ Interpret the result like this:
- Always read `workspace_check.session_open_check` before startup questions. The
Python preflight must confirm the CLEVER_ROOT-based session layout first:
three control-plane repos under `<CLEVER_ROOT>/clever-agent-workspace/`, target
repos under `<CLEVER_ROOT>/projects/<target-repo>/`.
repos under `<CLEVER_ROOT>/<target-repo>/`.
- Always read `preflight_check.agent_response_contract` before replying to a
CLEVER_ROOT-level prompt. It defines the response style: inherit the CLEVER
agent workflow, complete initial setup, then continue with the provided prompt.
Expand Down Expand Up @@ -389,7 +388,7 @@ Once the user approves:
- 새 target repo는 public으로 생성한다.
- Use `gh repo create <owner>/<repo> --public` for a newly created target repo.
- GitHub Free organization rulesets are enforced on public repositories; private repository enforcement requires GitHub Team, GitHub Pro, or GitHub Enterprise Cloud.
5. Clone or pull the target repo under `<CLEVER_ROOT>/projects/<target-repo>/`.
5. Clone or pull the target repo under `<CLEVER_ROOT>/<target-repo>/`.
6. Copy the target repo seed files before handoff:
- `docs/templates/target-repo-AGENTS.md` -> target repo `AGENTS.md`
- `docs/templates/target-repo-project-brief.md` -> target repo `docs/project-brief.md`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,6 @@
CONTEXT_REPO_NAME = "clever-context-monorepo"
CHANGE_REPO_NAME = "clever-change-control"
AGENT_WORKSPACE_DIR_NAME = "clever-agent-workspace"
PROJECTS_DIR_NAME = "projects"
START_REPO_NAME = "clever-agent-project"
CONTROL_PLANE_REPOS = (
START_REPO_NAME,
Expand Down Expand Up @@ -252,7 +251,7 @@ def infer_workspace_root(start: Path, git_root: Path | None = None) -> Path:
Preferred layout:

<CLEVER_ROOT>/clever-agent-workspace/{three control-plane repos}
<CLEVER_ROOT>/projects/<target-repo>
<CLEVER_ROOT>/<target-repo>

Legacy direct layout is still recognized so existing local checkouts can report
a useful migration-oriented preflight instead of failing path discovery.
Expand Down Expand Up @@ -297,15 +296,22 @@ def is_relative_to_path(path: Path, parent: Path) -> bool:
def build_session_open_check(*, cwd: Path, control_plane_root: Path, current_repo: str | None) -> dict[str, Any]:
clever_work_root = derive_clever_work_root(control_plane_root)
expected_control_plane_root = clever_work_root / AGENT_WORKSPACE_DIR_NAME
projects_root = clever_work_root / PROJECTS_DIR_NAME
target_repo_parent_root = clever_work_root
uses_expected_nested_layout = control_plane_root.resolve() == expected_control_plane_root.resolve()
cwd_under_control_plane = is_relative_to_path(cwd, control_plane_root)
cwd_under_projects = is_relative_to_path(cwd, projects_root)
cwd_under_clever_root = is_relative_to_path(cwd, clever_work_root)
cwd_is_clever_root = cwd.resolve() == clever_work_root.resolve()
cwd_under_target_repo_area = (
cwd_under_clever_root
and not cwd_under_control_plane
and not cwd_is_clever_root
and current_repo not in CONTROL_PLANE_REPOS
)
opened_from_start_repo = current_repo == START_REPO_NAME and cwd_under_control_plane
opened_from_control_plane_repo = current_repo in CONTROL_PLANE_REPOS and cwd_under_control_plane

if uses_expected_nested_layout:
status = "pass" if (opened_from_control_plane_repo or cwd_under_projects) else "fail"
status = "pass" if (opened_from_control_plane_repo or cwd_under_target_repo_area) else "fail"
layout_mode = "clever-root-with-agent-workspace"
else:
status = "legacy-layout" if opened_from_control_plane_repo else "fail"
Expand All @@ -317,17 +323,17 @@ def build_session_open_check(*, cwd: Path, control_plane_root: Path, current_rep
"clever_root": str(clever_work_root),
"control_plane_root": str(control_plane_root),
"expected_control_plane_root": str(expected_control_plane_root),
"projects_root": str(projects_root),
"target_repo_parent_root": str(target_repo_parent_root),
"cwd_under_control_plane_root": cwd_under_control_plane,
"cwd_under_projects_root": cwd_under_projects,
"cwd_under_target_repo_parent_root": cwd_under_target_repo_area,
"opened_from_start_repo": opened_from_start_repo,
"opened_from_control_plane_repo": opened_from_control_plane_repo,
"message": (
"Session path matches the CLEVER_ROOT layout."
if status == "pass"
else "Session uses the legacy direct control-plane layout; prefer <CLEVER_ROOT>/clever-agent-workspace for the three agent repos."
if status == "legacy-layout"
else "Session is not opened from the expected CLEVER_ROOT control-plane or projects layout."
else "Session is not opened from the expected CLEVER_ROOT control-plane or target repo layout."
),
}

Expand Down Expand Up @@ -427,7 +433,7 @@ def build_workspace_check(start: Path, *, current_repo_maintenance: bool = False
"clever_root": str(clever_root),
"clever_work_root": session_open_check["clever_root"],
"control_plane_root": session_open_check["control_plane_root"],
"projects_root": session_open_check["projects_root"],
"target_repo_parent_root": session_open_check["target_repo_parent_root"],
"session_open_check": session_open_check,
"control_plane_complete": control_plane_complete,
"current_repo_is_start": current_repo_is_start,
Expand Down Expand Up @@ -747,7 +753,7 @@ def build_agent_response_contract(workspace_check: dict[str, Any]) -> dict[str,
"confirm the CLEVER_ROOT session layout with workspace_check.session_open_check",
"create or confirm the target repository only after the project-start gate",
"apply or confirm repository rules before normal development",
"clone or pull the target repo under <CLEVER_ROOT>/projects/<target-repo>",
"clone or pull the target repo under <CLEVER_ROOT>/<target-repo>",
"inject AGENTS.md, docs/project-brief.md, PR template, and ruleset script into the target repo root",
"after initial setup succeeds, continue according to the user's provided prompt",
]
Expand Down Expand Up @@ -1483,13 +1489,13 @@ def build_packet(
"clever-context-monorepo",
"clever-change-control",
],
"project_repositories_root": "<CLEVER_ROOT>/projects",
"target_repo_checkout": "<CLEVER_ROOT>/projects/<target-repo>",
"target_repo_parent_root": "<CLEVER_ROOT>",
"target_repo_checkout": "<CLEVER_ROOT>/<target-repo>",
"seed_injection_root": "target repo root",
},
"post_create_clone": [
"create-or-confirm public target repo after project-start approval",
"clone-or-pull the target repo under <CLEVER_ROOT>/projects/<target-repo>",
"clone-or-pull the target repo under <CLEVER_ROOT>/<target-repo>",
"copy target repo seed files into the target repo root before handoff",
"apply GitHub rulesets after dev exists",
"verify local checkout is ready for follow-on work",
Expand Down Expand Up @@ -1606,7 +1612,7 @@ def print_workspace_check(workspace_check: dict[str, Any]) -> None:
print(f"clever-root: {workspace_check['clever_root']}")
print(f"clever-work-root: {workspace_check['clever_work_root']}")
print(f"control-plane-root: {workspace_check['control_plane_root']}")
print(f"projects-root: {workspace_check['projects_root']}")
print(f"target-repo-parent-root: {workspace_check['target_repo_parent_root']}")
session_open_check = workspace_check.get("session_open_check", {})
print(f"session-open-check: {session_open_check.get('status')}")
print(f"session-open-message: {session_open_check.get('message')}")
Expand Down
11 changes: 5 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,12 @@ Recommended local layout:
clever-agent-project/
clever-context-monorepo/
clever-change-control/
projects/
<target-repo>/
<target-repo>/
```

`<CLEVER_ROOT>` is the top-level CLEVER work root. Keep the three agent/control
repositories inside `<CLEVER_ROOT>/clever-agent-workspace/`. Put real product/service target
repositories under `<CLEVER_ROOT>/projects/<target-repo>/`. When
repositories under `<CLEVER_ROOT>/<target-repo>/`. When
bootstrapping a target repo, clone or pull the remote repo into that project
folder, then inject the agent documents into the target repo root.

Expand Down Expand Up @@ -85,9 +84,9 @@ Read these preflight output fields before asking anything:
- `workspace_check.session_open_check`: the Python preflight's CLEVER_ROOT-based
session-open validation. It must confirm the expected structure
`<CLEVER_ROOT>/clever-agent-workspace/{three control-plane repos}` and
`<CLEVER_ROOT>/projects/<target-repo>` before startup work
`<CLEVER_ROOT>/<target-repo>` before startup work
proceeds. If it reports `legacy-layout`, treat it as a migration warning and
keep the target project checkout under `<CLEVER_ROOT>/projects/`. If it
keep the target project checkout under `<CLEVER_ROOT>/`. If it
reports `fail`, stop and fix the session location first.
- `auto_skipped_questions`: questions already answered by tool evidence, such as
GitHub login inference, startup location, or dirty-state inspection.
Expand Down Expand Up @@ -777,7 +776,7 @@ The expected operating flow is:
5. Anchor the root line in `clever-change-control`
6. Fix scoped execution
7. Apply or confirm the repo branch operating contract
8. Handoff to the target repository under `<CLEVER_ROOT>/projects/<target-repo>/`
8. Handoff to the target repository under `<CLEVER_ROOT>/<target-repo>/`
9. Feed rollout / rollback / release evidence back into `clever-change-control`

## If The Workspace Is Incomplete
Expand Down
15 changes: 7 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,20 +19,19 @@ CLEVER는 한 가지 앱 전용 흐름이 아니다. 사용자가 익숙한 도
첫 화면에서는 직접 shell 명령보다 **어떤 환경에서 시작하는지**를 먼저 고른다.
공통 원칙은 **3개 레포를 같은 로컬 workspace에 두고, 일반 시작은 `clever-agent-project`에서 진행한다**는 점이다.

권장 폴더 구조는 아래처럼 나눈다. `<CLEVER_ROOT>`는 전체 CLEVER 작업 루트이고, 에이전트 제어 평면은 `<CLEVER_ROOT>/clever-agent-workspace/`이며, 실제 제품/서비스 코드는 `<CLEVER_ROOT>/projects/<target-repo>/` 아래에 둔다. target repo를 만들거나 확인한 뒤에는 이 target repo 폴더에 원격 repo를 clone/pull 하고, 그 repo 루트에 `AGENTS.md`, `docs/project-brief.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `scripts/apply-github-rulesets.sh`를 주입한다.
권장 폴더 구조는 아래처럼 나눈다. `<CLEVER_ROOT>`는 전체 CLEVER 작업 루트이고, 에이전트 제어 평면은 `<CLEVER_ROOT>/clever-agent-workspace/`이며, 실제 제품/서비스 코드는 `<CLEVER_ROOT>/<target-repo>/` 아래에 둔다. target repo를 만들거나 확인한 뒤에는 이 target repo 폴더에 원격 repo를 clone/pull 하고, 그 repo 루트에 `AGENTS.md`, `docs/project-brief.md`, `.github/PULL_REQUEST_TEMPLATE.md`, `scripts/apply-github-rulesets.sh`를 주입한다.

```text
<CLEVER_ROOT>/
clever-agent-workspace/
clever-agent-project/
clever-context-monorepo/
clever-change-control/
projects/
<target-repo>/
AGENTS.md
docs/project-brief.md
.github/PULL_REQUEST_TEMPLATE.md
scripts/apply-github-rulesets.sh
<target-repo>/
AGENTS.md
docs/project-brief.md
.github/PULL_REQUEST_TEMPLATE.md
scripts/apply-github-rulesets.sh
```

브라우저에서 버튼과 텍스트 입력으로 한 번에 정리하려면 [GitHub Pages 시작 도우미](https://evnsolution.github.io/clever-agent-project/start/)를 사용한다. 버튼과 텍스트 입력으로 답한 뒤 최종 copy text를 만들고, 에이전트에 붙여 넣을 위치까지 안내한다.
Expand All @@ -51,7 +50,7 @@ CLEVER는 한 가지 앱 전용 흐름이 아니다. 사용자가 익숙한 도
- https://github.com/EVNSolution/clever-change-control.git
3. 이후 작업 기준은 <CLEVER_ROOT>/clever-agent-workspace/clever-agent-project 로 잡아줘.
4. clever-agent-project의 README와 AGENTS.md 지침을 읽고, 그 지침에 따라 preflight와 작업 준비를 진행해줘.
5. 실제 제품/서비스 target repo는 <CLEVER_ROOT>/projects/<target-repo>/ 아래에 준비해줘.
5. 실제 제품/서비스 target repo는 <CLEVER_ROOT>/<target-repo>/ 아래에 준비해줘.
6. target repo를 만들거나 확인한 뒤에는 clever-agent-project 지침에 따라 agent 문서를 target repo에 주입해줘.
7. 초기 준비가 끝나기 전에는 구현, 커밋, PR 생성을 시작하지 마.
8. 초기 준비가 성공하면 아래 형식으로 답해줘.
Expand Down
13 changes: 6 additions & 7 deletions docs/setting.md
Original file line number Diff line number Diff line change
Expand Up @@ -149,15 +149,14 @@ CLEVER 관련 저장소는 하나의 workspace root 아래에 두는 것을 권
clever-agent-project/
clever-change-control/
clever-context-monorepo/
projects/
<target-repo>/
<target-repo>/
```

`<CLEVER_ROOT>`는 전체 CLEVER 작업 루트다. 에이전트 제어 평면은 `<CLEVER_ROOT>/clever-agent-workspace/`이고, 3대 레포는 항상 그 안의 sibling으로 둔다.
실제 제품/서비스 원격 repo는 `<CLEVER_ROOT>/projects/<target-repo>/`
실제 제품/서비스 원격 repo는 `<CLEVER_ROOT>/<target-repo>/`
아래에 clone 또는 pull 한다. 새 target repo seed 파일은 이 target repo 루트에 주입한다.

generic CLEVER startup 세션은 `<CLEVER_ROOT>/clever-agent-workspace/clever-agent-project`에서 시작한다. 승인 후 target GitHub repo를 생성하거나 확인한 다음, `<CLEVER_ROOT>/projects/` 아래에 로컬 clone 또는 pull 하고 그 target repo 루트에서 새 세션을 시작한다.
generic CLEVER startup 세션은 `<CLEVER_ROOT>/clever-agent-workspace/clever-agent-project`에서 시작한다. 승인 후 target GitHub repo를 생성하거나 확인한 다음, `<CLEVER_ROOT>/` 아래에 로컬 clone 또는 pull 하고 그 target repo 루트에서 새 세션을 시작한다.

예외는 sibling control-plane repo 자체를 직접 수정하는 경우다.

Expand Down Expand Up @@ -353,7 +352,7 @@ PR 정보를 wiki에 올리는 것이 아니다. wiki에는 필요한 서비스/

### 새 target repo 초기 seed 파일

새 target repo를 만들거나 첫 target repo를 bootstrap할 때는 프로젝트 기획 초안과 agent 실행 절차서를 분리해서 넣는다. 주입 위치는 `<CLEVER_ROOT>/projects/<target-repo>/`에 clone/pull된 target repo 루트다.
새 target repo를 만들거나 첫 target repo를 bootstrap할 때는 프로젝트 기획 초안과 agent 실행 절차서를 분리해서 넣는다. 주입 위치는 `<CLEVER_ROOT>/<target-repo>/`에 clone/pull된 target repo 루트다.

- [target repo AGENTS template](templates/target-repo-AGENTS.md) -> target repo `AGENTS.md`
- [target repo project brief template](templates/target-repo-project-brief.md) -> target repo `docs/project-brief.md`
Expand Down Expand Up @@ -394,9 +393,9 @@ pull/clone, target repo agent 문서 주입을 먼저 끝낸 뒤 "초기 작업

`workspace_check.session_open_check`는 Python preflight가 현재 세션이
`<CLEVER_ROOT>` 기준으로 열렸는지 확인한 결과다. `pass`이면
`<CLEVER_ROOT>/clever-agent-workspace/`와 `<CLEVER_ROOT>/projects/` 구조가 맞다.
`<CLEVER_ROOT>/clever-agent-workspace/`와 `<CLEVER_ROOT>/` 구조가 맞다.
`legacy-layout`이면 기존 direct control-plane layout에서 실행 중이라는 뜻이므로
새 target repo는 반드시 `<CLEVER_ROOT>/projects/<target-repo>/`에
새 target repo는 반드시 `<CLEVER_ROOT>/<target-repo>/`에
둔다. `fail`이면 작업 질문으로 내려가기 전에 세션 위치를 먼저 고친다.

`true`이면 내부 `workspace_check.agent_action`이 아래 중 하나를 돌려준다.
Expand Down
Loading