[#358] 🤖 - Develop

.agents/skills/product-specification/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: product-specification
+description: Create, revise, or review repository product and engineering specifications, SDDs, and implementation RFCs with explicit architecture, test budgets, documentation, bounded configuration, and user-facing GitHub UX. Use when a document will guide implementation or acceptance; do not use for implementation-only tasks or informal answers.
+---
+
+# Product Specification
+
+Produce a specification that lets product, engineering, reviewers, and
+operators understand the same intended product and verify when it is complete.
+
+Before drafting or reviewing, read these repository sources in full:
+
+- [Product Specification Standard](../../../specs/README.md)
+- [Specification template](../../../specs/_template.md)
+
+Use existing code, workflows, documentation, configuration, and observed
+failures as evidence. Follow the repository's Graphify rules before broad source
+exploration. Research external behavior when it is unstable, provider-specific,
+safety-critical, or central to the decision, and link primary sources.
+
+## Working method
+
+1. Establish current behavior and evidence before proposing changes.
+2. Separate product requirements, implementation choices, recommended defaults,
+   safety invariants, non-goals, and open decisions.
+3. Describe the complete user/operator journey, including pending, successful,
+   partial, blocked, retried, and canceled states.
+4. Apply Clean Architecture to the project's real boundaries: identify pure
+   decisions, use cases, semantic ports, adapters, composition, presentation,
+   state ownership, trust boundaries, and executable dependency constraints.
+5. Define configuration as a bounded product contract: defaults, values/ranges,
+   invalid combinations, precedence, persistence, migration, and intentionally
+   non-configurable safety rules.
+6. Treat issues, PRs, comments, labels, checks, summaries, CLI output, and docs as
+   UI when people rely on them. Show representative content and navigation, not
+   only the data or API behind it.
+7. Make complex relationships visual with a small diagram, state table,
+   timeline, or Markdown wireframe. Always provide an adjacent textual
+   equivalent and never rely on color or emoji alone.
+8. Define a numeric, risk-derived test budget with distribution by behavior
+   area, coverage expectations, integration/replay/race/security cases, and any
+   required human UX evidence. A count alone is never sufficient.
+9. Specify documentation deliverables for users, setup, configuration,
+   operations/recovery, migration, and architecture as applicable.
+10. Finish with observable acceptance scenarios, requirement traceability, an
+    implementation sequence, and a Definition of Done containing every quality
+    gate.
+
+## Quality boundary
+
+Be proportional: simple changes can mark sections not applicable with a reason.
+Never omit architecture, testing, documentation, configuration, UX, security,
+or operations merely because the implementation has not been designed yet.
+
+Prefer realistic states, messages, and links in examples while clearly
+distinguishing examples from fixed configuration. Keep the primary product view
+plain and close to the user's language; place internal identifiers, provider
+DTOs, stack traces, and low-level diagnostics in technical detail.
+
+Do not declare a spec ready while a decision that can materially change
+architecture, public behavior, data safety, or acceptance remains unresolved.

.cursor/rules/architecture.mdc

@@ -1,70 +1,40 @@
 ---
-description: Copilot – entry points, flow, and key paths
+description: Current architecture, boundaries, and key source paths
 alwaysApply: true
 ---
 
-# Architecture & Key Paths
-
-## Entry and main flow
-
-1. **GitHub Action**: `src/actions/github_action.ts` reads inputs, builds `Execution`, calls `mainRun(execution)` from `common_action.ts`.
-2. **CLI**: `src/actions/local_action.ts` same flow with CLI/config inputs.
-3. **common_action.ts**: Sets up; calls `waitForPreviousRuns(execution)` (sequential workflow); then:
-   - **Single action** → `SingleActionUseCase`
-   - **Issue** → `IssueCommentUseCase` or `IssueUseCase`
-   - **Pull request** → `PullRequestReviewCommentUseCase` or `PullRequestUseCase`
-   - **Push** → `CommitUseCase`
-
-## Key paths
-
-| Area | Path | Purpose |
-|------|------|--------|
-| Action entry | `src/actions/github_action.ts` | Reads inputs, builds Execution |
-| CLI entry | `src/cli.ts` → `local_action.ts` | Same flow, local inputs |
-| Shared flow | `src/actions/common_action.ts` | mainRun, waitForPreviousRuns, dispatch to use cases |
-| Use cases | `src/usecase/` | issue_use_case, pull_request_use_case, commit_use_case, single_action_use_case |
-| Single actions | `src/usecase/actions/` | check_progress, detect_errors, recommend_steps, think, initial_setup, create_release, create_tag, publish_github_action, deployed_action |
-| Steps (issue) | `src/usecase/steps/issue/` | check_permissions, close_not_allowed_issue, assign_members, update_title, update_issue_type, link_issue_project, check_priority_issue_size, prepare_branches, remove_issue_branches, remove_not_needed_branches, label_deploy_added, label_deployed_added, move_issue_to_in_progress, answer_issue_help_use_case (question/help on open). On issue opened: RecommendStepsUseCase (non release/question/help) or AnswerIssueHelpUseCase (question/help). |
-| Steps (PR) | `src/usecase/steps/pull_request/` | update_title, assign_members (issue), assign_reviewers_to_issue, link_pr_project, link_pr_issue, sync_size_and_progress_from_issue, check_priority_pull_request_size, update_description (AI), close_issue_after_merging |
-| Steps (commit) | `src/usecase/steps/commit/` | notify commit, check size |
-| Steps (issue comment) | `src/usecase/steps/issue_comment/` | check_issue_comment_language (translation) |
-| Steps (PR review comment) | `src/usecase/steps/pull_request_review_comment/` | check_pull_request_comment_language (translation) |
-| Bugbot autofix & user request | `src/usecase/steps/commit/bugbot/` + `user_request_use_case.ts` | detect_bugbot_fix_intent_use_case (plan agent: is_fix_request, is_do_request, is_review_request, target_finding_ids), BugbotAutofixUseCase + runBugbotAutofixCommitAndPush (fix findings), DoUserRequestUseCase + runUserRequestCommitAndPush (generic “do this”). Permission: ProjectRepository.isActorAllowedToModifyFiles (org member, or repo owner/write collaborator for personal repos); natural-language mutation requires the bot mention. |
-| Manager (content) | `src/manager/` | description handlers, configuration_handler, markdown_content_hotfix_handler (PR description, hotfix changelog content) |
-| Models | `src/data/model/` | Execution, Issue, PullRequest, SingleAction, etc. |
-| Repos | `src/data/repository/` | branch_repository, issue_repository, workflow_repository, ai_repository (OpenCode), file_repository, project_repository |
-| Config | `src/utils/constants.ts` | INPUT_KEYS, ACTIONS, defaults |
-| Metadata | `action.yml` | Action inputs and defaults |
-
-## Single actions (by name)
-
-- `check_progress_action`, `detect_errors_action`, `recommend_steps_action` (need `single-action-issue`)
-- `think_action`, `initial_setup` (no issue)
-- `create_release` (version, title, changelog), `create_tag` (version), `publish_github_action`, `deployed_action` (issue)
-
-## CLI-only (not single actions)
-
-- **Do (AI assistant)**: `copilot do -p "..."` uses OpenCode build agent via `AiRepository.copilotMessage` in `src/cli.ts`. No workflow single-action equivalent.
-
-## Concurrency (sequential runs)
-
-`common_action.ts` calls `waitForPreviousRuns(execution)` (from `src/utils/queue_utils.ts`): lists workflow runs, waits until no previous run of the **same workflow name** is in progress/queued, then continues. Implemented in `WorkflowRepository.getActivePreviousRuns`.
-
-## Flow: issue comment & PR review comment (intent + permissions + actions)
-
-When the event is **issue_comment** or **pull_request_review_comment**, `common_action.ts` invokes `IssueCommentUseCase` or `PullRequestReviewCommentUseCase` respectively. Both follow the same flow:
-
-1. **Check language** (e.g. translation): `CheckIssueCommentLanguageUseCase` / `CheckPullRequestCommentLanguageUseCase`.
-2. **Detect intent** (OpenCode plan agent): `DetectBugbotFixIntentUseCase` runs and returns a payload with:
-   - `isFixRequest`: user asked to fix one or more bugbot findings.
-   - `isDoRequest`: user asked to perform some other change/task in the repo (generic “do this”).
-   - `targetFindingIds`: when fix request, which finding ids to fix.
-   - `context`, `branchOverride`: for autofix (e.g. branch from open PR when on issue comment).
-3. **Permission check**: `ProjectRepository.isActorAllowedToModifyFiles(owner, actor, token)`:
-   - If repo **owner is an organization**: actor must be a **member** of that org.
-   - If repo **owner is a user**: actor must be the **same** as the owner.
-   - If not allowed and the intent was fix or do-request, we skip the file-modifying use cases and log; Think still runs so the user gets a response.
-4. **Run at most one file-modifying action** (only if allowed):
-   - If **fix request** with targets and context: `BugbotAutofixUseCase` → `runBugbotAutofixCommitAndPush` → optionally `markFindingsResolved`.
-   - Else if **do request** (and not fix): `DoUserRequestUseCase` → `runUserRequestCommitAndPush`.
-5. **Think**: If **no** file-modifying action ran (no intent, no permission, or no targets/context), we run `ThinkUseCase` so the user gets an AI reply (e.g. answer to a question).
+# Architecture and key paths
+
+Use `_agent/docs/architecture.md` as the concise repository map and
+`docs/development/architecture.mdx` plus `docs/dependency-rules.md` as the
+authoritative architecture contract. Do not duplicate an older source tree or
+action catalog in this rule.
+
+The dependency direction is:
+
+```text
+entrypoint
+  -> lifecycle/composition root
+    -> application use case/workflow
+      -> semantic application port
+        -> specialized adapter
+          -> provider client/detail
+```
+
+Current source roots:
+
+- `src/actions/`: GitHub and local runtime boundaries.
+- `src/application/usecases/`: orchestration and workflows.
+- `src/application/policies/`: deterministic application decisions.
+- `src/application/ports/`: semantic capability contracts.
+- `src/data/model/` and `src/domain/`: provider-neutral core.
+- `src/data/repository/`: specialized external adapters.
+- `src/infrastructure/github/`: Octokit and GraphQL transports.
+- `src/infrastructure/composition/`: the only dependency assembly layer.
+
+Release and hotfix deployment use the durable orchestration state machine. The
+canonical callback actions are declared in `src/data/model/action_types.ts`;
+there is no second deployment or branch-merge implementation.
+
+Before changing a boundary, inspect the current source and run the architecture
+tests. Graphify output is a navigation aid, not an architecture authority.