@chinhae/atw-cli 0.3.6 → 0.4.0

package/dist/templates/atw/scripts/common/session_context.py

@@ -10,6 +10,7 @@ Provides:
     output_json               - Print JSON
     output_text               - Print text
     get_update_hint           - Once-per-session "update available" line
+    conventions_context       - A general project's `<conventions>` block
 """
 
 from __future__ import annotations
@@ -22,7 +23,7 @@ import sys
 from pathlib import Path
 
 from .active_task import resolve_context_key
-from .config import get_git_packages
+from .config import get_git_packages, get_project_mode
 from .git import run_git
 from .noob_mode import noob_mode_reminder
 from .packages_context import get_packages_section
@@ -264,12 +265,18 @@ def _collect_package_git_info(
     return discovered
 
 
-def _append_root_git_context(lines: list[str], root_git_info: dict) -> None:
+def _append_root_git_context(
+    lines: list[str], root_git_info: dict, package_git_info: list[dict]
+) -> None:
     """Append root Git status without misleading non-Git roots."""
     lines.append("## GIT STATUS")
     if not root_git_info["isRepo"]:
         lines.append("Root is not a Git repository.")
-        lines.append("Run Git commands from the package repository paths listed below.")
+        # 普通文件夹下面没有列出任何仓库，这句指路只在确实列了仓库时才说。
+        if package_git_info:
+            lines.append(
+                "Run Git commands from the package repository paths listed below."
+            )
     else:
         lines.append(f"Branch: {root_git_info['branch']}")
         if root_git_info["isClean"]:
@@ -488,6 +495,54 @@ def get_update_hint(repo_root: Path, context_key: str | None = None) -> str | No
     )
 
 
+# =============================================================================
+# Conventions (general projects)
+# =============================================================================
+
+# The one flat place a `general` project keeps what its user asked for more
+# than once. A `dev` project spreads coding guidelines over per-package,
+# per-layer directories under spec/ and lists their indexes at session start;
+# a general project has this single file, handed to the AI in full instead.
+#
+# It sits under spec/ on purpose: that directory is already the user's own
+# content everywhere it matters — never overwritten by `atw update`, never
+# hash-tracked, checked for uncommitted work before `atw uninstall`.
+FILE_CONVENTIONS = "conventions.md"
+
+# Project-relative, as the AI should read and write it.
+CONVENTIONS_PATH = f"{DIR_WORKFLOW}/{DIR_SPEC}/{FILE_CONVENTIONS}"
+
+_CONVENTIONS_HEADER = (
+    f"Source: {CONVENTIONS_PATH} — what this project's user asked for more than "
+    "once. Follow it in every reply."
+)
+
+
+def conventions_context(repo_root: Path) -> str:
+    """The `<conventions>` block for a `general` project, "" for a `dev` one.
+
+    The session-start hooks and `get_context.py` all take the block from here,
+    so every platform says the same thing; the OpenCode plugin has its own port
+    (`lib/session-utils.js`) — keep the two in step.
+
+    A general project always gets the block: with the file missing or empty it
+    still names the place, so the AI knows where the first entry goes.
+    """
+    if get_project_mode(repo_root) != "general":
+        return ""
+    body = ""
+    try:
+        body = (repo_root / CONVENTIONS_PATH).read_text(encoding="utf-8").strip()
+    except OSError:
+        pass
+    if not body:
+        return (
+            f"<conventions>\n{_CONVENTIONS_HEADER} Nothing is written there yet."
+            "\n</conventions>"
+        )
+    return f"<conventions>\n{_CONVENTIONS_HEADER}\n\n{body}\n</conventions>"
+
+
 # =============================================================================
 # JSON Output
 # =============================================================================
@@ -607,6 +662,13 @@ def get_context_text(repo_root: Path | None = None) -> str:
     lines.append(f"Name: {developer}")
     lines.append("")
 
+    # A general project's conventions reach platforms without a hook the same
+    # way the noob-mode reminder below does.
+    conventions = conventions_context(repo_root)
+    if conventions:
+        lines.append(conventions)
+        lines.append("")
+
     # Platforms without a hook learn about noob mode from this output alone.
     noob_mode = noob_mode_reminder(repo_root)
     if noob_mode:
@@ -614,16 +676,14 @@ def get_context_text(repo_root: Path | None = None) -> str:
         lines.append("")
 
     root_git_info = _collect_root_git_info(repo_root)
-    _append_root_git_context(lines, root_git_info)
+    package_git_info = _collect_package_git_info(
+        repo_root,
+        discover_unconfigured=not root_git_info["isRepo"],
+    )
+    _append_root_git_context(lines, root_git_info, package_git_info)
 
     # Package git repos — independent sub-repositories
-    _append_package_git_context(
-        lines,
-        _collect_package_git_info(
-            repo_root,
-            discover_unconfigured=not root_git_info["isRepo"],
-        ),
-    )
+    _append_package_git_context(lines, package_git_info)
 
     # Current task
     lines.append("## CURRENT TASK")
@@ -851,16 +911,14 @@ def get_context_text_record(repo_root: Path | None = None) -> str:
     lines.append("")
 
     root_git_info = _collect_root_git_info(repo_root)
-    _append_root_git_context(lines, root_git_info)
+    package_git_info = _collect_package_git_info(
+        repo_root,
+        discover_unconfigured=not root_git_info["isRepo"],
+    )
+    _append_root_git_context(lines, root_git_info, package_git_info)
 
     # Package git repos — independent sub-repositories
-    _append_package_git_context(
-        lines,
-        _collect_package_git_info(
-            repo_root,
-            discover_unconfigured=not root_git_info["isRepo"],
-        ),
-    )
+    _append_package_git_context(lines, package_git_info)
 
     # CURRENT TASK
     lines.append("## CURRENT TASK")

package/dist/templates/atw/scripts/common/task_store.py

@@ -28,6 +28,7 @@ from pathlib import Path
 from .config import (
     get_codex_dispatch_mode,
     get_packages,
+    get_project_mode,
     get_session_auto_commit,
     is_monorepo,
     resolve_package,
@@ -263,10 +264,30 @@ def _parse_meta_pairs(pairs: list[str] | None) -> dict[str, str] | None:
     return meta
 
 
-def _default_prd_content(title: str, description: str | None = None) -> str:
+def _default_prd_content(
+    title: str, description: str | None = None, general: bool = False
+) -> str:
     """Return the default PRD skeleton created with every task."""
-    goal = (description or "").strip() or "TBD."
     heading = title.strip() or "Untitled task"
+    if general:
+        # The user of a general project opens this file themselves: the three
+        # parts its workflow has the AI write, and no word about tickets.
+        unwritten = "(Not written yet.)"
+        return f"""# {heading}
+
+## What will be done
+
+{(description or "").strip() or unwritten}
+
+## What will not be done
+
+{unwritten}
+
+## What counts as done
+
+{unwritten}
+"""
+    goal = (description or "").strip() or "TBD."
     return f"""# {heading}
 
 ## Goal
@@ -471,7 +492,7 @@ def cmd_create(args: argparse.Namespace) -> int:
     # back to the checked-out branch when the default can't be resolved
     # (no remote configured, offline, etc.) — the pre-existing behavior.
     # --base-branch lets the caller override both when neither is correct.
-    _, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
+    branch_rc, branch_out, _ = run_git(["branch", "--show-current"], cwd=repo_root)
     current_branch = branch_out.strip() or "main"
     explicit_base_branch: str | None = getattr(args, "base_branch", None)
     if explicit_base_branch:
@@ -482,15 +503,17 @@ def cmd_create(args: argparse.Namespace) -> int:
             base_branch = resolved_base_branch
         else:
             base_branch = current_branch
-            print(
-                colored(
-                    f"warning: could not resolve the repository's default branch "
-                    f"(no remote configured, offline, etc.); stamping base_branch as "
-                    f"the checked-out branch '{base_branch}'. Pass --base-branch to override.",
-                    Colors.YELLOW,
-                ),
-                file=sys.stderr,
-            )
+            # 普通文件夹里没有仓库也没有检出的分支，这条提醒说的事并不存在。
+            if branch_rc == 0:
+                print(
+                    colored(
+                        f"warning: could not resolve the repository's default branch "
+                        f"(no remote configured, offline, etc.); stamping base_branch as "
+                        f"the checked-out branch '{base_branch}'. Pass --base-branch to override.",
+                        Colors.YELLOW,
+                    ),
+                    file=sys.stderr,
+                )
 
     task_data = {
         "id": slug,
@@ -535,10 +558,12 @@ def cmd_create(args: argparse.Namespace) -> int:
                 )
         return 1
 
+    general = get_project_mode(repo_root) == "general"
+
     prd_path = task_dir / "prd.md"
     if not prd_path.exists():
         prd_path.write_text(
-            _default_prd_content(args.title, description),
+            _default_prd_content(args.title, description, general),
             encoding="utf-8",
         )
 
@@ -554,8 +579,11 @@ def cmd_create(args: argparse.Namespace) -> int:
     # check.jsonl), so a seeded-but-empty implement manifest would only be a
     # file nobody curates. The `start` gate only refuses manifests that exist
     # with zero curated entries, so an absent one is not gated.
+    #
+    # A general project installs no sub-agents, so nobody would curate or read
+    # the manifest there either: it is not seeded, and `start` needs no flag.
     created_jsonl = False
-    if _has_subagent_platform(repo_root):
+    if not general and _has_subagent_platform(repo_root):
         jsonl_path = task_dir / "check.jsonl"
         if not jsonl_path.exists():
             jsonl_path.write_text("", encoding="utf-8")
@@ -654,28 +682,42 @@ def cmd_create(args: argparse.Namespace) -> int:
     print(colored(f"Created task: {dir_name}", Colors.GREEN), file=sys.stderr)
     print("", file=sys.stderr)
     print(colored("Next steps:", Colors.BLUE), file=sys.stderr)
-    print("  - Fill prd.md with requirements and acceptance criteria", file=sys.stderr)
-    print("  - Lightweight task: PRD-only is valid", file=sys.stderr)
-    print("  - Complex task: slice it into issues/NN-slug.md tickets before task.py start", file=sys.stderr)
-    if created_jsonl:
+    if general:
+        # A general project has no tickets, no sub-agents to curate context
+        # for and no `continue` command: its workflow has the AI do the rest.
+        print("  - Talk it through with the user until what they want is clear", file=sys.stderr)
         print(
-            "  - Curate check.jsonl (created empty) as the spec/research "
-            "manifest before task.py start when sub-agents need context:",
+            "  - Write prd.md: what will be done, what will not, what counts as done; "
+            "show it to the user and wait for them to confirm",
             file=sys.stderr,
         )
         print(
-            '      one JSON object per line — {"file": "<path>", "reason": "<why>"}; '
-            "spec/research docs only, no code paths",
+            "  - Once confirmed: task.py start <task>, then do the work",
             file=sys.stderr,
         )
+    else:
+        print("  - Fill prd.md with requirements and acceptance criteria", file=sys.stderr)
+        print("  - Lightweight task: PRD-only is valid", file=sys.stderr)
+        print("  - Complex task: slice it into issues/NN-slug.md tickets before task.py start", file=sys.stderr)
+        if created_jsonl:
+            print(
+                "  - Curate check.jsonl (created empty) as the spec/research "
+                "manifest before task.py start when sub-agents need context:",
+                file=sys.stderr,
+            )
+            print(
+                '      one JSON object per line — {"file": "<path>", "reason": "<why>"}; '
+                "spec/research docs only, no code paths",
+                file=sys.stderr,
+            )
+            print(
+                "      list available specs: python3 .atw/scripts/get_context.py --mode packages",
+                file=sys.stderr,
+            )
         print(
-            "      list available specs: python3 .atw/scripts/get_context.py --mode packages",
+            "  - Use the ATW `continue` command or phase context to decide the next step",
             file=sys.stderr,
         )
-    print(
-        "  - Use the ATW `continue` command or phase context to decide the next step",
-        file=sys.stderr,
-    )
     print("", file=sys.stderr)
 
     # Output relative path for script chaining
@@ -1442,6 +1484,15 @@ def _auto_commit_archive(
         )
         return True
 
+    # 普通文件夹没有可提交的地方：这不是故障，说一句就够了，不把 git 的报错原文打出来。
+    rc, _, _ = run_git(["rev-parse", "--is-inside-work-tree"], cwd=repo_root)
+    if rc != 0:
+        print(
+            "[OK] Not a git repository — task archived, skipping auto-commit.",
+            file=sys.stderr,
+        )
+        return True
+
     source_rel = f"{DIR_WORKFLOW}/{DIR_TASKS}/{task_name}"
     rc, tracked_out, _ = run_git(
         ["ls-files", "--", source_rel],

package/dist/templates/atw/scripts/noob_mode.py

@@ -3,9 +3,10 @@
 Switch noob mode (plain-language replies) for the current developer.
 
 Usage:
-    python3 noob_mode.py on        Turn it on
-    python3 noob_mode.py off       Turn it off
-    python3 noob_mode.py status    Show whether it is on
+    python3 noob_mode.py on        Turn it on, whatever the project default
+    python3 noob_mode.py off       Turn it off, whatever the project default
+    python3 noob_mode.py status    Show whether it is on, and whether that is
+                                   this developer's setting or the project default
 
 The switch is personal — see common/noob_mode.py.
 """
@@ -14,7 +15,8 @@ from __future__ import annotations
 
 import sys
 
-from common.noob_mode import is_noob_mode_on, set_noob_mode
+from common.config import get_project_mode
+from common.noob_mode import is_noob_mode_on, noob_mode_choice, set_noob_mode
 from common.paths import DIR_SCRIPTS, DIR_WORKFLOW, FILE_DEVELOPER, get_repo_root
 
 
@@ -35,6 +37,16 @@ def main() -> None:
         sys.exit(1)
 
     print(f"Noob mode: {'on' if is_noob_mode_on(repo_root) else 'off'}")
+    if action == "status":
+        # stdout stays the one-line answer; where it comes from goes to stderr.
+        if noob_mode_choice(repo_root) is None:
+            source = (
+                f"project default (mode: {get_project_mode(repo_root)}), "
+                "no personal setting"
+            )
+        else:
+            source = "your own setting"
+        print(f"Source: {source}", file=sys.stderr)
 
 
 if __name__ == "__main__":

package/dist/templates/atw/scripts/task.py

@@ -9,6 +9,7 @@ Usage:
     python3 task.py validate <dir>              # Validate jsonl files
     python3 task.py list-context <dir>          # List jsonl entries
     python3 task.py start <dir>                 # Set active task, record current branch
+    python3 task.py resume <dir>                # Set active task, leave its status as it is
     python3 task.py current [--source] [--json] # Show active task
     python3 task.py finish                      # Clear active task
     python3 task.py set-branch <dir> <branch>   # Set git branch
@@ -48,6 +49,7 @@ from common.active_task import (
     resolve_context_key,
     set_active_task,
 )
+from common.config import get_project_mode
 from common.git import current_branch_name
 from common.io import (
     describe_json_read_failure,
@@ -186,14 +188,13 @@ def _record_start_state(
         )
 
 
-def cmd_start(args: argparse.Namespace) -> int:
-    """Set active task."""
-    repo_root = get_repo_root()
-    task_input = args.dir
-
+def _resolve_session_task(task_input: str, repo_root: Path) -> tuple[Path, str] | None:
+    """Resolve a task ref to its directory and the repo-relative path stored
+    in the session pointer. Prints the reason and returns None when it cannot.
+    """
     if not task_input:
         print(colored("Error: task directory or name required", Colors.RED))
-        return 1
+        return None
 
     # Resolve task directory (supports task name, relative path, or absolute path)
     full_path = resolve_task_dir(task_input, repo_root)
@@ -202,19 +203,70 @@ def cmd_start(args: argparse.Namespace) -> int:
         # resolve_task_dir already named the exact reason on stderr. A second,
         # generic line on stdout would split one diagnosis across two streams
         # and bury the specific message.
-        return 1
+        return None
 
     if not full_path.is_dir():
         print(colored(f"Error: Task not found: {task_input}", Colors.RED))
         print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.atw/tasks/01-31-my-task')")
+        return None
+
+    # Convert to relative path for storage. repo_root is resolved because
+    # full_path already is (resolve_task_dir only returns paths inside the
+    # resolved root), so an unresolved repo_root would mismatch under a
+    # symlink (e.g. /tmp on macOS) and reject a perfectly normal task.
+    try:
+        task_dir = full_path.relative_to(repo_root.resolve()).as_posix()
+    except ValueError:
+        # resolve_task_dir already refused everything outside the repo, so
+        # this is unreachable in practice. Refuse rather than fall back to
+        # str(full_path) — that fallback (a lexical relative_to() paired with
+        # an absolute-path fallback) is exactly the pattern that let a `..`
+        # ref escape into storage before this fix.
+        print(colored(f"Error: Task not found: {task_input}", Colors.RED))
+        print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.atw/tasks/01-31-my-task')")
+        return None
+
+    return full_path, task_dir
+
+
+def _print_no_session_identity(command: str) -> None:
+    # Degraded mode: no session identity available.
+    # Hook didn't inject ATW_CONTEXT_ID (common on Windows + Claude Code,
+    # --continue resume path, fork distribution, hooks disabled, etc.). Skip
+    # per-session pointer write; AI continues based on conversation context.
+    print(colored(
+        "ℹ Session identity not available; active-task pointer not persisted "
+        "this session (degraded mode). AI continues based on conversation context.",
+        Colors.YELLOW,
+    ))
+    print(colored(
+        "Hint: run inside an AI IDE/session that exposes session identity, "
+        f"or set ATW_CONTEXT_ID before running task.py {command}.",
+        Colors.YELLOW,
+    ))
+
+
+def cmd_start(args: argparse.Namespace) -> int:
+    """Set active task."""
+    repo_root = get_repo_root()
+    task_input = args.dir
+
+    resolved = _resolve_session_task(task_input, repo_root)
+    if resolved is None:
         return 1
+    full_path, task_dir = resolved
 
     # Context-manifest gate: a seeded-but-uncurated implement/check
     # manifest means every sub-agent dispatched for this task runs with zero
     # spec context, and nothing downstream surfaces that to the main session.
     # An absent manifest is not gated — create seeds the files only on
     # sub-agent-capable platforms, so absence means no sub-agent reads them.
-    if not getattr(args, "allow_empty_context", False):
+    # Nor is a general project: it installs no sub-agents, and a task brought
+    # over from dev may still carry an empty manifest.
+    if (
+        not getattr(args, "allow_empty_context", False)
+        and get_project_mode(repo_root) != "general"
+    ):
         empty_manifests = [
             name
             for name in ("implement.jsonl", "check.jsonl")
@@ -232,39 +284,10 @@ def cmd_start(args: argparse.Namespace) -> int:
             print("  Intentionally empty? Re-run start with --allow-empty-context")
             return 1
 
-    # Convert to relative path for storage. repo_root is resolved because
-    # full_path already is (resolve_task_dir only returns paths inside the
-    # resolved root), so an unresolved repo_root would mismatch under a
-    # symlink (e.g. /tmp on macOS) and reject a perfectly normal task.
-    try:
-        task_dir = full_path.relative_to(repo_root.resolve()).as_posix()
-    except ValueError:
-        # resolve_task_dir already refused everything outside the repo, so
-        # this is unreachable in practice. Refuse rather than fall back to
-        # str(full_path) — that fallback (a lexical relative_to() paired with
-        # an absolute-path fallback) is exactly the pattern that let a `..`
-        # ref escape into storage before this fix.
-        print(colored(f"Error: Task not found: {task_input}", Colors.RED))
-        print("Hint: Use task name (e.g., 'my-task') or full path (e.g., '.atw/tasks/01-31-my-task')")
-        return 1
-
     task_json_path = full_path / FILE_TASK_JSON
 
     if not resolve_context_key():
-        # Degraded mode: no session identity available.
-        # Hook didn't inject ATW_CONTEXT_ID (common on Windows + Claude Code,
-        # --continue resume path, fork distribution, hooks disabled, etc.). Skip
-        # per-session pointer write; AI continues based on conversation context.
-        print(colored(
-            "ℹ Session identity not available; active-task pointer not persisted "
-            "this session (degraded mode). AI continues based on conversation context.",
-            Colors.YELLOW,
-        ))
-        print(colored(
-            "Hint: run inside an AI IDE/session that exposes session identity, "
-            "or set ATW_CONTEXT_ID before running task.py start.",
-            Colors.YELLOW,
-        ))
+        _print_no_session_identity("start")
 
         # Still flip task.json status: discover → implement so downstream phases proceed.
         if task_json_path.is_file():
@@ -290,6 +313,36 @@ def cmd_start(args: argparse.Namespace) -> int:
         return 1
 
 
+def cmd_resume(args: argparse.Namespace) -> int:
+    """Set active task without touching its record.
+
+    `start` is also "begin the work": it moves a planning-stage task to
+    `implement`. Picking a task up in a later session must not do that — a
+    task still being discussed would read as started before it was agreed.
+    So this writes the session pointer and nothing else: no status, no branch,
+    no manifest gate, no `after_start` hook.
+    """
+    repo_root = get_repo_root()
+
+    resolved = _resolve_session_task(args.dir, repo_root)
+    if resolved is None:
+        return 1
+    _, task_dir = resolved
+
+    if not resolve_context_key():
+        _print_no_session_identity("resume")
+        return 0
+
+    active = set_active_task(task_dir, repo_root)
+    if not active:
+        print(colored("Error: Failed to set current task", Colors.RED))
+        return 1
+
+    print(colored(f"✓ Current task set to: {task_dir}", Colors.GREEN))
+    print(f"Source: {active.source}")
+    return 0
+
+
 def cmd_finish(args: argparse.Namespace) -> int:
     """Clear active task."""
     repo_root = get_repo_root()
@@ -556,6 +609,7 @@ Usage:
   python3 task.py validate <dir>                     Validate jsonl files
   python3 task.py list-context <dir>                 List jsonl entries
   python3 task.py start <dir>                        Set active task; records the checked-out branch when unset
+  python3 task.py resume <dir>                       Set active task; its status and record stay as they are
   python3 task.py current [--source]                 Show active task
   python3 task.py finish                             Clear active task
   python3 task.py set-branch <dir> <branch>          Set git branch
@@ -713,6 +767,12 @@ def main() -> int:
         help="Start even when implement.jsonl / check.jsonl have no curated entries",
     )
 
+    # resume
+    p_resume = subparsers.add_parser(
+        "resume", help="Set active task, leave its status as it is"
+    )
+    p_resume.add_argument("dir", help="Task directory")
+
     # current
     p_current = subparsers.add_parser("current", help="Show active task")
     p_current.add_argument("--source", action="store_true",
@@ -807,6 +867,7 @@ def main() -> int:
         "validate": cmd_validate,
         "list-context": cmd_list_context,
         "start": cmd_start,
+        "resume": cmd_resume,
         "current": cmd_current,
         "finish": cmd_finish,
         "set-branch": cmd_set_branch,